Layout·component·@astryxdesign/core

Stack

Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.

Open in Playground @astryxdesign/core/Stack

Showcases and examples

3 documented examples

Stack — Directions

Badges arranged horizontally and vertically in side-by-side cards.

Open Playground ↗

Preview loads on approachPreview loads on approach

Exact source · stack-directions

// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

import {HStack, VStack} from '@astryxdesign/core/Layout';
import {Token} from '@astryxdesign/core/Token';

export default function StackDirections() {
  return (
    <HStack gap={10} hAlign="center">
      <HStack gap={2} vAlign="center">
        <Token label="Horizontal" />
        <Token label="Horizontal" />
        <Token label="Horizontal" />
      </HStack>
      <VStack gap={2}>
        <Token label="Vertical" />
        <Token label="Vertical" />
        <Token label="Vertical" />
      </VStack>
    </HStack>
  );
}

Usage

Stack arranges items in a row or column with consistent spacing. Use the gap prop to control the space between items.

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.
Nest stacks inside stacks; try wrap="wrap" first to let items flow to the next line.

Typed props

Stack

Prop	Type and behavior
`direction`	`'horizontal' \| 'vertical'` · default '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` · default 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'` · default 'nowrap' Flex wrap behavior.
`as`	`ElementType` · default '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={{}}.

HStack

Prop	Type and behavior
`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` · default 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'` · default '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'` · default 'nowrap' Flex wrap behavior.
`as`	`ElementType` · default '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={{}}.

VStack

Prop	Type and behavior
`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` · default 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'` · default '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'` · default 'nowrap' Flex wrap behavior.
`as`	`ElementType` · default 'div' HTML element to render as the stack container.
`children`	`ReactNode` Stack content.

StackItem

Prop	Type and behavior
`size`	`'static' \| 'fill'` · default 'static' Flex grow behavior: static keeps natural size, fill expands to consume remaining space.
`isScrollable`	`boolean` · default 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` · default 'div' HTML element to render as the item wrapper.
`children`	`ReactNode` Item content.

Anatomy

Stack container · required

Layout container that arranges content along one flex axis.

Item · optional

Optional StackItem wrapper that controls one item in the stack.

Content · optional

Caller-supplied content rendered by a Stack or StackItem.

Theming

Targets

astryx-stack

Visual props: direction, gap, wrap

astryx-stack-item

Visual props: size