Skip to main content
Join the waitlist

Stack

Stacks children in a row or column with one consistent gap.

import { Stack } from "@usefragments/ui";Source

Preview

import { Stack } from '@usefragments/ui';
import { Text } from '@usefragments/ui';

<Stack gap="sm">
  <Text>One</Text>
  <Text>Two</Text>

Usage

Use when

  • Spacing a short row or column of elements
  • Any one-directional flexbox arrangement
  • A row that should fold into a column when its pane gets narrow (collapseBelow)

Avoid when

  • Two-dimensional layouts (use Grid)
  • Grouping buttons into one control (use ButtonGroup)
  • Page shell regions (use AppShell)

Implementation notes

  • Set gap once on the parent instead of margins on children
  • gap reads the one layout scale; there is no numeric second scale
  • collapseBelow answers the Stack's own width, so it holds inside panes, cards and dialogs
  • Use as="nav" or as="ul" so the markup stays semantic
  • divided draws one Separator between children; lists stay valid

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Examples

Horizontal Stack

Children flow along the inline axis.

import { Button } from '@usefragments/ui';
import { Stack } from '@usefragments/ui';

<Stack direction="row" gap="sm" justify="end">
  <Button variant="ghost">Cancel</Button>
  <Button>Save</Button>

Collapse Below

Side by side while the Stack is at least 32rem wide, a column below that.

import { Field } from '@usefragments/ui';
import { Input } from '@usefragments/ui';
import { Stack } from '@usefragments/ui';

<Stack collapseBelow="32rem" gap="md">
  <Field>

Divided

One Separator between each child.

import { Stack } from '@usefragments/ui';
import { Text } from '@usefragments/ui';

<Stack gap="md" divided>
  <Text>Section one</Text>
  <Text>Section two</Text>

Semantic List

as="ul" with dividers keeps only li children.

import { Stack } from '@usefragments/ui';

<Stack as="ul" gap="sm" divided>
  <li>Checkout</li>
  <li>Billing</li>
  <li>Settings</li>

API reference

Component props
Prop
Type
Default
Description
alignStackAlign | undefinedcenterstartendbaselinestretchNot setCross-axis alignment
asStackElement | undefineddivarticleasidefooterheadermainnavolsectionuldivHTML element to render
childrenRequiredReact.ReactNodeNot setElements to arrange
classNamestring | undefinedNot set—
collapseBelowstring | undefinedNot setA CSS length. Children share the row in equal parts while the Stack is at least this wide and stack into a column below it. Measured against the Stack's own width, never the viewport. Implies a row.
directionStackDirection | undefinedrowcolumncolumnDirection children flow in
dividedboolean | undefinedfalseDraw a Separator between children: horizontal in a column, vertical in a row. Inside ul/ol each divider is a hidden li, so the list stays valid. Ignored when collapseBelow is set.
gapStackGap | undefinedxssmmdlgnonexlmdSpace between children on the layout gap scale: 0, 4, 8, 12, 16, 24
justifyStackJustify | undefinedcenterstartendbetweenNot setMain-axis alignment
styleReact.CSSProperties | undefinedNot set—
wrapboolean | undefinedfalseAllow items to wrap

Accessibility

  • Use semantic elements (nav, section, etc.) via "as" prop
  • Maintains source order for screen readers
  • No accessibility concerns with visual arrangement

Related components

  • GridalternativeUse Grid for complex 2D layouts
  • ButtonGroupsiblingButtonGroup is specialized for buttons
  • BoxsiblingBox for single-element styling

Next steps