Stack
Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.
Installation
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
Requires React 19+, base CSS and a Theme provider. See Setup.
Stack
Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.
Usage guidance
- Use the gap prop for spacing between items; don't add margins manually.
- Use StackItem with size="fill" to make one item stretch and fill the leftover space.
- Avoid: Nest stacks inside stacks; try wrap="wrap" first to let items flow to the next line.
Theming API
{
"targets": [
{
"className": "astryx-stack",
"visualProps": [
"direction",
"gap",
"wrap"
]
},
{
"className": "astryx-stack-item",
"visualProps": [
"size"
]
}
]
}
Stack
Unified stack layout component with a direction prop. Use direction="horizontal" for left-to-right flow or direction="vertical" (default) for top-to-bottom. For convenience, HStack and VStack are pre-configured wrappers.
| Prop | Type | Default | Description |
|---|---|---|---|
| direction | 'horizontal' | 'vertical' | 'vertical' | Direction of the stack layout. 'horizontal' flows items left-to-right (like HStack), 'vertical' flows top-to-bottom (like VStack). Note: the value is 'horizontal', NOT 'row'. |
| gap | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4". | |
| padding | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inner padding on all sides, using the spacing scale. Pass as a JSX number expression e.g. padding={3}. | |
| paddingInline | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inline (horizontal) padding. Overrides padding on the inline axis when both are set. | |
| paddingInlineStart | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inline-start padding, using the spacing scale (left in LTR, right in RTL). Overrides paddingInline and padding on that edge only. | |
| paddingInlineEnd | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inline-end padding, using the spacing scale (right in LTR, left in RTL). Overrides paddingInline and padding on that edge only. | |
| paddingBlock | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Block (vertical) padding. Overrides padding on the block axis when both are set. | |
| paddingBlockStart | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Block-start (top) padding, using the spacing scale. Overrides paddingBlock and padding on that edge only. | |
| paddingBlockEnd | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Block-end (bottom) padding, using the spacing scale. Overrides paddingBlock and padding on that edge only. | |
| isScrollable | boolean | false | Enables scrollable overflow (overflow: auto). |
| width | SizeValue | Width of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| height | SizeValue | Height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| maxWidth | SizeValue | Maximum width of the stack container. | |
| minHeight | SizeValue | Minimum height of the stack container. | |
| hAlign | 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | 'stretch' | Horizontal alignment. When direction='horizontal': main-axis (justify-content). When direction='vertical': cross-axis (align-items). | |
| vAlign | 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | 'stretch' | Vertical alignment. When direction='horizontal': cross-axis (align-items). When direction='vertical': main-axis (justify-content). | |
| justify | 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | Main-axis alignment alias. Resolves to hAlign (horizontal) or vAlign (vertical). Note: use 'between', NOT 'space-between'. | |
| align | 'start' | 'center' | 'end' | 'stretch' | Cross-axis alignment alias. Mirrors CSS align-items. | |
| wrap | 'nowrap' | 'wrap' | 'wrap-reverse' | 'nowrap' | Flex wrap behavior. |
| as | ElementType | 'div' | HTML element to render as the stack container. |
| children | ReactNode | Stack content. | |
| xstyle | StyleXStyles | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}. |
H Stack
Horizontal stack for arranging items left-to-right. Supports polymorphic rendering.
| Prop | Type | Default | Description |
|---|---|---|---|
| gap | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4". | |
| padding | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inner padding on all sides, using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Matches the padding prop on Card, LayoutContent, and LayoutPanel. Pass as a JSX number expression e.g. padding={3}. | |
| paddingInline | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inline (horizontal) padding, using the spacing scale. Overrides padding on the inline axis when both are set. | |
| paddingInlineStart | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inline-start padding, using the spacing scale (left in LTR, right in RTL). Overrides paddingInline and padding on that edge only. | |
| paddingInlineEnd | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inline-end padding, using the spacing scale (right in LTR, left in RTL). Overrides paddingInline and padding on that edge only. | |
| paddingBlock | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Block (vertical) padding, using the spacing scale. Overrides padding on the block axis when both are set. | |
| paddingBlockStart | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Block-start (top) padding, using the spacing scale. Overrides paddingBlock and padding on that edge only. | |
| paddingBlockEnd | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Block-end (bottom) padding, using the spacing scale. Overrides paddingBlock and padding on that edge only. | |
| isScrollable | boolean | false | Enables scrollable overflow (overflow: auto). Matches isScrollable on LayoutContent and LayoutPanel. |
| width | SizeValue | Width of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| height | SizeValue | Height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| maxWidth | SizeValue | Maximum width of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| minHeight | SizeValue | Minimum height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| hAlign | 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | Horizontal (main-axis) alignment of items. | |
| vAlign | 'start' | 'center' | 'end' | 'stretch' | 'stretch' | Vertical (cross-axis) alignment of items. |
| justify | 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | Main-axis alignment alias for hAlign. Mirrors CSS justify-content. | |
| align | 'start' | 'center' | 'end' | 'stretch' | Cross-axis alignment alias for vAlign. Mirrors CSS align-items. | |
| wrap | 'nowrap' | 'wrap' | 'wrap-reverse' | 'nowrap' | Flex wrap behavior. |
| as | ElementType | 'div' | HTML element to render as the stack container. |
| children | ReactNode | Stack content. | |
| xstyle | StyleXStyles | StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}. |
V Stack
Vertical stack for arranging items top-to-bottom. Supports polymorphic rendering.
| Prop | Type | Default | Description |
|---|---|---|---|
| gap | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Spacing step (number literal): 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10. Pass as a JSX number expression e.g. gap={4}, NOT a string like gap="4". | |
| padding | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inner padding on all sides, using the spacing scale (0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10). Matches the padding prop on Card, LayoutContent, and LayoutPanel. Pass as a JSX number expression e.g. padding={3}. | |
| paddingInline | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inline (horizontal) padding, using the spacing scale. Overrides padding on the inline axis when both are set. | |
| paddingInlineStart | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inline-start padding, using the spacing scale (left in LTR, right in RTL). Overrides paddingInline and padding on that edge only. | |
| paddingInlineEnd | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Inline-end padding, using the spacing scale (right in LTR, left in RTL). Overrides paddingInline and padding on that edge only. | |
| paddingBlock | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Block (vertical) padding, using the spacing scale. Overrides padding on the block axis when both are set. | |
| paddingBlockStart | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Block-start (top) padding, using the spacing scale. Overrides paddingBlock and padding on that edge only. | |
| paddingBlockEnd | 0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | Block-end (bottom) padding, using the spacing scale. Overrides paddingBlock and padding on that edge only. | |
| isScrollable | boolean | false | Enables scrollable overflow (overflow: auto). Matches isScrollable on LayoutContent and LayoutPanel. |
| width | SizeValue | Width of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| height | SizeValue | Height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| maxWidth | SizeValue | Maximum width of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| minHeight | SizeValue | Minimum height of the stack container. Numbers are treated as pixels, strings are used as-is (e.g., '100%'). | |
| hAlign | 'start' | 'center' | 'end' | 'stretch' | 'stretch' | Horizontal (cross-axis) alignment of items. |
| vAlign | 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | Vertical (main-axis) alignment of items. | |
| justify | 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly' | Main-axis alignment alias for vAlign. Mirrors CSS justify-content. | |
| align | 'start' | 'center' | 'end' | 'stretch' | Cross-axis alignment alias for hAlign. Mirrors CSS align-items. | |
| wrap | 'nowrap' | 'wrap' | 'wrap-reverse' | 'nowrap' | Flex wrap behavior. |
| as | ElementType | 'div' | HTML element to render as the stack container. |
| children | ReactNode | Stack content. |
Stack Item
Stack item for controlling individual item behavior within a stack. Supports polymorphic rendering.
| Prop | Type | Default | Description |
|---|---|---|---|
| size | 'static' | 'fill' | 'static' | Flex grow behavior: static keeps natural size, fill expands to consume remaining space. |
| isScrollable | boolean | false | Enables scrollable overflow (overflow: auto). StackItem already applies the flex min-height/min-width reset, so <StackItem size="fill" isScrollable> is a complete scroll region. Matches isScrollable on LayoutContent and LayoutPanel. |
| crossAlignSelf | 'start' | 'center' | 'end' | 'stretch' | Override the cross-axis alignment for this individual item, ignoring the parent stack alignment. | |
| as | ElementType | 'div' | HTML element to render as the item wrapper. |
| children | ReactNode | Item content. |
Anatomy
- Stack container: Layout container that arranges content along one flex axis.
- Item: Optional StackItem wrapper that controls one item in the stack.
- Content: Caller-supplied content rendered by a Stack or StackItem.
Examples
- Stack — Directions: Badges arranged horizontally and vertically in side-by-side cards.
- Stack Item: StackItem can be used within HStack or VStack for more granular control over individual item sizing and alignment, but is optional; stack children work without it.
- Stack — Alignment: Buttons positioned at the start, center, and end of a row.
- Stack — Fill Item: An avatar, text, and button in a row; the text stretches to fill the available space.
- StackItem — Fill: A static-width item next to one that fills the remaining space. Wrap stack children in StackItem when an item needs explicit sizing control.