Flex
Flex layout primitive for vertical or horizontal stacking with gap control. ⚠ Unlike CSS `flex-direction`, `direction` defaults to `vertical` — pass `direction="horizontal"` for a row.
Category: layout · WCAG 2.1-AA · layout, flex, stack, spacing
Props
| Prop | Type | Default | Description |
|---|---|---|---|
direction | 'vertical' | 'horizontal' | vertical | Flex direction. ⚠ Defaults to `vertical`, unlike CSS `flex-direction` (and unlike Chakra/MUI/Radix `Flex`, which default to a row) — `<Flex justify="between">` alone produces a centered vertical stack. |
gap | 1|2|3|4|5|6|8|10|12 | 4 | Spacing token step |
align | 'start'|'center'|'end'|'stretch' | — | align-items |
justify | 'start'|'center'|'end'|'between' | — | justify-content |
wrap | boolean | false | Allow wrapping |
size | 'auto' | 'fixed' | 'grow' | 'shrink' | auto | FlexItem: main-axis sizing. 'fixed' (flex: 0 0 auto) is what a fixed-width child like Sparkline needs; 'grow' takes the leftover width without shrinking; 'shrink' gives way but never grows. |
basis | string | — | FlexItem: flex-basis — the child's size before free space is distributed. Any CSS length. |
truncate | boolean | false | FlexItem: allow the child to shrink below its content width (releases the flex item's `min-width: auto` floor and ellipsizes). Without it a long unbreakable string pushes its siblings out of the row. |
Design tokens
--cascivo-space-*
When to use
- Arranging children vertically or horizontally with a consistent gap
- The default primitive for spacing a small set of elements in one direction
When not to use
- Two-dimensional layouts — use Grid
- Responsive auto-wrapping card collections — use AutoGrid
- A visual card-pile / overlapping avatars — that is `Stack` in @cascivo/react (an `offset` prop), a different component.
Examples
Vertical
Default vertical stack
<Flex gap={4}><div>A</div><div>B</div></Flex>Horizontal
Row layout
<Flex direction="horizontal" gap={2}><div>A</div><div>B</div></Flex>Toolbar: one field absorbs the row, the rest keep their width
Without FlexItem the Search takes the whole row and pushes the Select onto the next line
<Flex direction="horizontal" gap={2}>
<FlexItem size="grow" basis="0"><Search ariaLabel="Filter deployments" /></FlexItem>
<FlexItem size="fixed"><Select options={states} ariaLabel="State" /></FlexItem>
</Flex>Protecting a fixed-width child
Sparkline is fixed-width and will not shrink; `size="fixed"` keeps it out of flex sizing, `truncate` lets the URL beside it ellipsize instead of pushing it out
<Flex direction="horizontal" gap={3} align="center">
<FlexItem truncate>{deployment.url}</FlexItem>
<FlexItem size="fixed"><Sparkline data={points} label="Requests" /></FlexItem>
</Flex>