Components / Structure

Stack

Lays children out in a column with a gap from the space scale. For a row, use Inline.

Gaps use space tokens

When to use

Forms, settings panels, card content, any vertical rhythm.
Instead of margins on each child.

Usage

tsx

import { Stack } from "@arshad-shah/cynosure";

<Stack gap="4">
  <TextField label="Name" />
  <TextField label="Email" />
</Stack>
<Stack as="ul" gap="2" align="start">…</Stack>
<Stack padding="6">…</Stack>

gap is a space token from "0" to "10" (default "4"). direction is column (default) or row; a row that centres its items and can wrap is Inline, which is a Stack in a row. align is start, center, end, stretch or baseline. justify is start, center, end or between. as picks a neutral element (div, section, ul, ol, nav, aside, header, footer, span).

Defaults and layout props

Padding

padding pads all four sides with a space token. paddingInline (the sides) and paddingBlock (top and bottom) each win over padding for their axis, and "0" counts as a value. The padding is inside the stack's width. For the page's own column and gutters, use Container.

tsx

<Stack padding="6" paddingBlock="8">…</Stack>

Padding uses space tokens

App shells

grow, shrink, fill, minSize and overflow size a box inside its parent, for an app whose header and status bar stay put while the middle scrolls. grow takes the free space along a flex parent's row or column (a status bar item that pushes the rest to the end: no spacer component needed); shrink={false} keeps a box at its size when room runs out; fill is 100% of the parent both ways; minSize="0" lets a flex or grid child be smaller than its content, so what is inside it can scroll instead of pushing the page longer; overflow is hidden, auto or visible. For a scrolling area people read with the keyboard, follow or jump to the end of, use ScrollArea.

tsx

<Stack fill gap="0">
  <Toolbar label="Editor">…</Toolbar>
  <Stack grow minSize="0">
    <ScrollArea label="Results">…</ScrollArea>
  </Stack>
  <Inline gap="2">
    <Text>main</Text>
    <Inline grow>…</Inline>
    <Text>Ln 1, Col 1</Text>
  </Inline>
</Stack>

Fill and min size let achild scroll

Props

Every prop of Stack
Prop	What it does	Type	Default
`gap`	Space token between children.	`Space`
`direction`	Lay the children out in a column (the default) or in a row. For a row, Inline adds wrapping and centring.	`"row" \| "column"`
`align`	How children line up across the stack (horizontally in a column); `baseline` lines up text in a row.	`"start" \| "end" \| "center" \| "stretch" \| "baseline"`
`justify`	How children are spread along the stack (vertically in a column); `between` pushes them apart.	`"start" \| "end" \| "center" \| "between"`
`sticky`	Stay in view while the page scrolls past (`position: sticky`), inside its parent. In a Grid, make the GridItem sticky instead, or give the Grid `align="start"`: a box stretched to its row has nowhere to move.	`boolean`
`stickyOffset`	With `sticky`: any CSS length between the top of the scrolling area and the box, e.g. a header's height. Default 0.	`string`	`0`
`as`	Neutral layout element to render (never an interactive one).	`"div" \| "section" \| "aside" \| "ul" \| "ol" \| "nav" \| "header" \| "footer" \| "span"`
`className`	Added to the root element, for layout.	`string`
`style`	Layout only.	`CSSProperties`
`children`	The items to stack.	`ReactNode`
`data-testid`	Passed to the root element, for tests.	`string`
`padding`	Space token of padding on all four sides of the box. Default: none.	`Space`	`none`
`paddingInline`	Space token of padding at the inline start and end (left and right in English). Wins over `padding`.	`Space`
`paddingBlock`	Space token of padding at the block start and end (top and bottom in English). Wins over `padding`.	`Space`
`hideBelow`	Hidden while the window is narrower than this breakpoint (`md`: below 45rem).	`"sm" \| "md" \| "lg" \| "xl"`
`hideAbove`	Hidden from this breakpoint upwards (`md`: 45rem and wider).	`"sm" \| "md" \| "lg" \| "xl"`
`grow`	Take the free space along the parent's row or column (`flex-grow: 1`), pushing the boxes after it to the end.	`boolean`
`shrink`	`false` keeps the box at its own size when the parent's row or column runs out of room. Default true.	`boolean`	`true`
`fill`	As wide and as tall as the parent's content box (`100%` both ways).	`boolean`
`minSize`	`"0"` lets the box be smaller than its content, so a child can scroll instead of overflowing the page. A flex or grid child is otherwise at least as tall (and wide) as what it holds. Default: the CSS automatic minimum.	`"0"`	`the CSS automatic minimum`
`overflow`	What happens to content that does not fit: `hidden` clips it, `auto` scrolls it, `visible` lets it overflow (the default). A box that scrolls content with nothing focusable in it should be a ScrollArea with a `label`, so keyboard users can scroll it.	`BoxOverflow`

Generated from the type definitions in @arshad-shah/cynosure 0.5.0.

Notes

as never renders an interactive element.
className and style are for layout only.
The gap and the padding are space tokens (--cy-space-*), so they follow the theme's spacing.
A nested Stack has no padding unless it asks for it; it never inherits its parent's.

Inline · Container · Card · Field

These examples run Cynosure 0.5.0 (commit 50ce30b), the version on npm.

When to useLink to "When to use"

UsageLink to "Usage"

PaddingLink to "Padding"

App shellsLink to "App shells"

PropsLink to "Props"

NotesLink to "Notes"