Stack

Direction Variants

Spacing Variants

Preview spacing values with the Spacing Scale Generator.

Alignment Variants

Wrapping Behavior

When a Stack wraps, it begins to behave somewhat like a grid — use Grid if you need precise row/column control in the wrapped state.

Stack Properties

CSS Custom Properties

Design Token Mappings

Stack's token usage is almost entirely spacing-focused. The Spacing Scale Generator is the primary tool for calibrating gap values across your system. Use the Flexbox Generator to test alignment and distribution combinations visually.

Stack States

Like Grid, Stack is a non-interactive layout primitive. Its "states" are responsive behaviors and content-driven adaptations:

Responsive Direction Pattern

The most common responsive Stack pattern switches from horizontal to vertical on smaller screens:

.stack-responsive {
  display: flex;
  flex-direction: row;
  gap: var(--space-4);
}

@media (max-width: 640px) {
  .stack-responsive {
    flex-direction: column;
  }
}

Many design systems provide a responsive or breakpoint prop for this:

<Stack direction={{ base: 'column', md: 'row' }} gap={16}>
  <Box>Left</Box>
  <Box>Right</Box>
</Stack>

Null Child Handling

A well-implemented Stack must handle null, undefined, and false children gracefully — these are common in conditional rendering. CSS gap handles this naturally since it only applies between rendered elements. Older margin-based implementations required explicit null filtering.

Accessibility Requirements

Stack itself is semantically neutral — it's a <div> with Flexbox styles. Accessibility depends on the semantic HTML used within and as the stack container.

WCAG Success Criteria:

• 1.3.1 Info and Relationships (Level A): Stack provides no semantic structure. If stacked items form a list, use <Stack as="ul"> with <li> children. If they form a navigation, use <Stack as="nav">. The visual grouping created by Stack must be backed by semantic HTML.
• 1.3.2 Meaningful Sequence (Level A): DOM order must match visual order. Avoid column-reverse or row-reverse for content where reading sequence matters — screen readers follow DOM order, not visual order. A chat interface using column-reverse must ensure the DOM order still makes logical sense for assistive technology users.
• 2.4.3 Focus Order (Level A): When using row-reverse or column-reverse, keyboard focus follows DOM order. If visual order contradicts DOM order, users will perceive focus as jumping unpredictably. Match DOM order to visual reading order.
• 1.4.10 Reflow (Level AA): At 320px viewport width, horizontal Stacks must reflow to vertical. Use responsive direction changes or wrapping to prevent horizontal scrolling. Test at 400% zoom.
• 4.1.2 Name, Role, Value (Level A): When using the divider prop, ensure inserted dividers use role="separator" if they convey structure, or role="presentation" if purely decorative. See Divider for details.

Semantic Polymorphism:

The as prop is Stack's most important accessibility feature. Use it to render the correct semantic element:

Check that any decorative dividers between stack items don't interfere with screen reader flow using the Contrast Checker to verify their visual treatment.

Usage Guidelines

Do:

• Use Stack as your default layout component for single-axis arrangements — it handles 80% of layout needs
• Use the as prop to render semantically correct HTML (<ul>, <nav>, <section>)
• Pair Stack with design tokens for consistent spacing (gap={space.4} instead of gap={16})
• Use the divider prop to insert consistent separators between children without manual placement
• Switch from row to column at appropriate breakpoints for responsive layouts
• Combine Stack with Grid for complex layouts: Grid for the page structure, Stack for the content within each grid cell

Don't:

• Use Stack when you need two-dimensional layout — use Grid instead
• Use column-reverse or row-reverse for content where reading order matters (WCAG 1.3.2)
• Mix Stack and manual margins — let gap handle all spacing between children
• Nest too many Stacks deeply without considering whether a Grid would be cleaner
• Use Stack for overlapping or absolutely positioned elements
• Forget that wrapping HStacks create multi-line layouts that might be better served by Grid

Composition Patterns:

Design System Implementations

Chakra UI provides <Stack>, <VStack>, and <HStack>. Stack accepts direction (row | column, supports responsive objects like { base: 'column', md: 'row' }), spacing (gap using Chakra's space scale), align (align-items), justify (justify-content), wrap, divider (a React element inserted between children, typically <StackDivider />), and shouldWrapChildren (wraps each child in a <div> for consistent spacing in older browsers). Chakra's Stack is the most-referenced implementation and popularized the divider prop pattern.

Material Design 3 (MUI) provides <Stack> with direction (row | column | row-reverse | column-reverse, supports responsive breakpoint objects), spacing (multiplied by the 8px theme unit), divider (React element), alignItems, justifyContent, and the useFlexGap prop (uses CSS gap instead of margin — this is the modern recommended approach). MUI's Stack is built on top of Box with flex styles.

Ant Design provides <Space> rather than Stack. Props include direction (horizontal | vertical), size (small | middle | large | number), wrap, align (start | end | center | baseline), and split (divider element). Space.Compact is a specialized variant that removes gaps and adjusts border-radius for tightly grouped elements like input + button combinations. Ant's implementation uses margin rather than CSS gap for broader browser support.

Radix UI provides <Flex> in their Radix Themes package with direction, gap, align, justify, wrap, and as (polymorphic). It's a general-purpose Flexbox primitive rather than a Stack-specific component, but serves the same role.

Tailwind CSS handles stacking with utility classes: flex flex-col gap-4 (VStack), flex flex-row gap-3 items-center (HStack). The space-y-{n} and space-x-{n} utilities add margins between children (older pattern), while gap-{n} uses CSS gap (modern pattern). Responsive direction changes use prefix variants: flex-col md:flex-row.

react-aria (Adobe Spectrum) provides <Flex> with direction, gap, alignItems, justifyContent, wrap, and dimension props. Their implementation handles responsive props via a ResponsiveProp type that maps breakpoints to values.