Skip to content
Browse documentation
whisk/ui

Stack

Arrange related content with a consistent gap.

Overview

Stack is the portable one-dimensional layout primitive. Compared with Flex, it defaults to a column direction and a gap of 4; Flex defaults to a row and no gap.

Compare the layout primitives in the Choose a layout component table.

Use when

Related content needs a consistent one-dimensional gap.

Use instead

Use Grid when items need columns and rows, or Flex for explicit flexbox behavior.

Usage

First item

Second item

import { Stack, Text } from "@smoothie-framework/whisk-react";

<Stack gap={3}>
  <Text>First item</Text>
  <Text>Second item</Text>
</Stack>

Examples

Align

Stack stretches children across the cross axis by default. Set align="start" when controls should remain their natural width.

import { Button, Stack } from "@smoothie-framework/whisk-react";

<Stack align="start" gap={3}>
  <Button>Invite members</Button>
  <Button variant="secondary">Manage roles</Button>
</Stack>

Direction

Use Stack when related content changes from a vertical sequence to a row at a named breakpoint. Use StackRow when it is always horizontal.

Summary

Activity

import { Box, Stack, Text } from "@smoothie-framework/whisk-react";

<Stack direction={{ base: "column", md: "row" }} gap={3}>
  <Box padding={3} background="surface1" rounded="md"><Text>Summary</Text></Box>
  <Box padding={3} background="surface2" rounded="md"><Text>Activity</Text></Box>
</Stack>

Horizontal alignment

When Stack uses a row, align controls vertical alignment and justify controls horizontal distribution.

Workspace

Updated now

import { Stack, Text } from "@smoothie-framework/whisk-react";

<Stack direction="row" align="center" justify="between" gap={3}>
  <Text weight="semibold">Workspace</Text>
  <Text color="subtle">Updated now</Text>
</Stack>

Wrap

Set wrap when a horizontal Stack can run out of inline space. Keep a gap so the next line remains easy to scan.

Design

Engineering

Research

import { Box, Stack, Text } from "@smoothie-framework/whisk-react";

<Stack direction="row" wrap gap={2}>
  <Box paddingX={3} paddingY={2} background="surface2" rounded="full"><Text>Design</Text></Box>
  <Box paddingX={3} paddingY={2} background="surface2" rounded="full"><Text>Engineering</Text></Box>
  <Box paddingX={3} paddingY={2} background="surface2" rounded="full"><Text>Research</Text></Box>
</Stack>

Dividers

Stack does not add separators. When headings already establish the sections, use a decorative Divider for the visible rule.

Deployment

Production is healthy.

Billing

Your next invoice is due on May 1.

import { Divider, Heading, Stack, Text } from "@smoothie-framework/whisk-react";

<Stack gap={3}>
  <Heading level={4} size="sm">Deployment</Heading>
  <Text color="subtle">Production is healthy.</Text>
  <Divider decorative />
  <Heading level={4} size="sm">Billing</Heading>
  <Text color="subtle">Your next invoice is due on May 1.</Text>
</Stack>

Props

Component props

PropTypeDefaultDescription
gapResponsive<SpacingStep>4Set the space between sibling children from the spacing scale.
directionResponsive<row | column | row-reverse | column-reverse>columnChoose the main axis and order of children.
alignResponsive<start | center | end | stretch | baseline>stretchAlign children across the cross axis.
justifyResponsive<start | center | end | between | around | evenly>startDistribute children along the main axis.
wrapResponsive<boolean>falseAllow children to wrap when Stack uses a row direction.

Shared props

PropSupportedNotes
as / asChildYesChoose the rendered host with as, or merge the component props into one child with asChild.
Style propsYesUse the shared static style-prop surface. See Style props.
className / styleYesApplied to the rendered host.
refYesForwards to the rendered host.
Native HTML attributesYesNative attributes are forwarded to the rendered host.

Accessibility

Stack is a layout div, not a list, group, or landmark. Keep headings, landmarks, controls, and document order meaningful in its children. Insert a Divider explicitly when a visible separation carries meaning.