Stack

A 1D flex container with typed direction, alignment, and gap. The only component in @dashforge/tw that does flex — Box doesn't, Grid doesn't. When you read <Stack> in a JSX tree you instantly know it's flex; no <Box display="flex"> trap to hunt for in 500 lines of utility classes.

import { Stack, Button } from '@dashforge/tw';

<Stack direction="row" gap={3} justify="end">
  <Button variant="text">Cancel</Button>
  <Button color="primary">Save</Button>
</Stack>

Quick Start

{/* Vertical stack — the default */}
<Stack gap={4}>
  <TextField name="email" label="Email" />
  <TextField name="password" type="password" label="Password" />
  <Button type="submit" color="primary">Sign in</Button>
</Stack>

{/* Horizontal toolbar */}
<Stack direction="row" gap={2} align="center" justify="between">
  <Typography variant="h3">Workspace</Typography>
  <Button variant="outlined">Settings</Button>
</Stack>

direction defaults to 'col' — the most common case for forms, sidebars, panels.

Examples

Direction

import { Stack, Box, Typography } from '@dashforge/tw';

<Stack gap={3} sx="w-64">
  <Box variant="outlined" p={3} rounded="md">
    <Typography variant="body2">Row 1</Typography>
  </Box>
  <Box variant="outlined" p={3} rounded="md">
    <Typography variant="body2">Row 2</Typography>
  </Box>
  <Box variant="outlined" p={3} rounded="md">
    <Typography variant="body2">Row 3</Typography>
  </Box>
</Stack>

<Stack direction="col">vertical (default)</Stack>
<Stack direction="row">horizontal</Stack>
<Stack direction="col-reverse">last item first, vertically</Stack>
<Stack direction="row-reverse">last item first, horizontally</Stack>

Align + Justify

align controls the cross-axis (items-*), justify controls the main-axis (justify-*):

import { Stack, Box, Typography } from '@dashforge/tw';

<Stack direction="row" gap={3} align="center" justify="between" sx="w-full">
  <Stack direction="row" gap={2} align="center">
    <Box variant="solid" color="primary" p={2} rounded="md">
      <Typography variant="caption">DF</Typography>
    </Box>
    <Typography variant="body2">Dashforge</Typography>
  </Stack>
  <Typography variant="caption" color="muted">v0.2.0-beta</Typography>
</Stack>

{/* Header pattern: title left, actions right */}
<Stack direction="row" align="center" justify="between">
  <Typography variant="h3">Page title</Typography>
  <Stack direction="row" gap={2}>
    <Button variant="outlined">Settings</Button>
    <Button color="primary">Save</Button>
  </Stack>
</Stack>

{/* Centered hero content */}
<Stack align="center" justify="center" gap={4} fullHeight>
  <Typography variant="h1">Welcome</Typography>
  <Typography variant="body1" color="muted">Pick up where you left off</Typography>
  <Button color="primary">Continue</Button>
</Stack>

Gap

Token-scale steps (same set as Box spacing): 0 · '0.5' · 1 · 2 · 3 · 4 · 6 · 8 · 12 · 16 · 24

<Stack gap={1}>tight</Stack>
<Stack gap={4}>comfortable</Stack>
<Stack gap={8}>spacious</Stack>

Wrap

<Stack direction="row" wrap gap={2}>
  {tags.map(tag => <Chip key={tag}>{tag}</Chip>)}
</Stack>

Without wrap, a row of children that overflows horizontally clips. With wrap, children flow to the next line.

Divider

The classic settings-list pattern — a thin separator between rows:

<Stack
  gap={3}
  divider={<Box variant="outlined" color="neutral" sx="h-px border-0 border-t" />}
>
  <SettingRow label="Public access" />
  <SettingRow label="Email notifications" />
  <SettingRow label="2FA" />
</Stack>

The divider node is rendered N-1 times between children. One child = no divider. Strings/numbers work too:

<Stack direction="row" divider=" · ">
  <a href="/home">Home</a>
  <a href="/about">About</a>
  <a href="/contact">Contact</a>
</Stack>
{/* Renders: Home · About · Contact */}

⚠️ Fragments count as one child. If you wrap items in <>...</>, the divider sees the fragment as a single boundary. Hoist items out of the fragment when you need a divider between them.

Composition with Box

The canonical card pattern — Box for the surface, Stack for the rhythm:

<Box variant="outlined" rounded="xl" p={6}>
  <Stack gap={4}>
    <Typography variant="h3">Notification preferences</Typography>
    <Stack gap={3}>
      <SettingRow label="Email digest" />
      <SettingRow label="Push notifications" />
    </Stack>
    <Stack direction="row" gap={2} justify="end">
      <Button variant="text">Cancel</Button>
      <Button color="primary">Save</Button>
    </Stack>
  </Stack>
</Box>

Polymorphic — as and asChild

{/* `as` — semantic nav with flex layout */}
<Stack as="nav" direction="row" gap={4}>
  <a href="/docs">Docs</a>
  <a href="/about">About</a>
</Stack>

{/* `asChild` — Stack styles paint onto an existing element */}
<Stack direction="row" gap={2} asChild>
  <ul>
    <li>One</li>
    <li>Two</li>
  </ul>
</Stack>

asChild wins over as when both are passed. Note: divider is silently ignored under asChild (Slot wraps a single child).

Stack vs Grid — which to use

The rule: 1 axis → Stack, 2 axes → Grid. Asymmetric flex (one fixed + one fill) stays in Stack because you don't need column math.

Theme defaults

Configure <Stack> defaults application-wide through the theme's components field.

import { patchTheme } from '@dashforge/tw-theme';

patchTheme({
  components: {
    Stack: {
      defaults: { direction: 'col', gap: 4, align: 'stretch' },
    },
  },
});

Configurable axes (StackVariantProps):

Precedence chain (lowest → highest):

1. defaultVariants from the internal stackVariants recipe (direction: 'col').
2. theme.components.Stack.defaults — application-wide override.
3. Instance prop (<Stack direction="row" />) — wins over theme.
4. sx — wins over the resolved variant class via tailwind-merge.

useComponentDefaults('Stack') reactively re-renders every mounted Stack when patchTheme runs at runtime.

API

Props

Slots & slotProps

<Stack> has no slots. It renders a single flex-column (or row) DOM element wrapping its children — there is no anatomy to target separately. The optional divider prop injects a node between children but does not carry a slot API.

The slotProps API pattern only exists on compound components with multiple visually distinct regions. Examples: <Menu>, <DataGrid>, <Autocomplete>.

For <Stack>, use sx on the root; style your children directly (they're your own components).

Variant catalogue

import { stackVariants } from '@dashforge/tw';
// stackVariants({ direction: 'row', gap: 4, justify: 'between' }) → className

Notes

• Stack is the ONLY flex in @dashforge/tw. Box doesn't do flex. The naming is the contract — when you see <Stack> you know it's flex without reading further.
• divider is runtime-only — TV can't encode the "render between children" logic as a class. The walk is O(n) where n is the number of children. For typical UI (n ≤ ~10) the cost is negligible.
• Fragments count as one child for divider purposes. React.Children.toArray does not recursively flatten Fragments. If you need a divider between items inside a Fragment, hoist them out.
• No surface props (variant, color, rounded, shadow, border). Wrap Stack inside a Box if you need a card-shaped flex container — Box paints the surface, Stack arranges.

When NOT to use

• For 2D layouts with both rows and columns — use <Grid>. Stack is strictly 1D.
• For surfaces (cards, panels, banners) — wrap Stack inside <Box>. Stack has no border/bg/shadow props.
• For a single child when you don't need direction/gap/divider — just use the child directly. Stack adds a wrapping <div> you don't need.