Stack

Flex layout as props, on a closed spacing scale.

First
Second
Third
import * as stylex from "@stylexjs/stylex"
import { VStack } from "@/components/ui/stack"
import { color, radius, space } from "@/theme/tokens.stylex"

const styles = stylex.create({
  card: {
    borderRadius: radius.md,
    borderWidth: 1,
    borderStyle: "solid",
    backgroundColor: `color-mix(in oklab, ${color.muted} 40%, transparent)`,
    paddingInline: space.s3,
    paddingBlock: space.s2,
  },
})

export default function StackDemo() {
  return (
    <VStack gap={2} width="16rem">
      <div {...stylex.props(styles.card)}>First</div>
      <div {...stylex.props(styles.card)}>Second</div>
      <div {...stylex.props(styles.card)}>Third</div>
    </VStack>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/stack

Needs the arene setup first.

Usage

import { HStack, Stack, VStack } from "@/components/ui/stack"
<HStack align="center" gap={2}>
  <Icon />
  <span>Label</span>
</HStack>

Use Stack when the styling is only the layout. Give an element with its own background, border or type a stylex.create() block, and put its layout there.

Direction

Stack runs vertically. HStack and VStack fix direction. Pass direction yourself only when the value is computed.

One
Two
Three
One
Two
import * as stylex from "@stylexjs/stylex"
import { HStack, VStack } from "@/components/ui/stack"
import { color, radius, space } from "@/theme/tokens.stylex"

const styles = stylex.create({
  card: {
    borderRadius: radius.md,
    borderWidth: 1,
    borderStyle: "solid",
    backgroundColor: `color-mix(in oklab, ${color.muted} 40%, transparent)`,
    paddingInline: space.s3,
    paddingBlock: space.s2,
  },
})

export default function StackDirection() {
  return (
    <VStack gap={4}>
      <HStack gap={2}>
        <div {...stylex.props(styles.card)}>One</div>
        <div {...stylex.props(styles.card)}>Two</div>
        <div {...stylex.props(styles.card)}>Three</div>
      </HStack>
      <VStack gap={2}>
        <div {...stylex.props(styles.card)}>One</div>
        <div {...stylex.props(styles.card)}>Two</div>
      </VStack>
    </VStack>
  )
}

Alignment

Use justify and align for justify-content and align-items, without the flex- prefixes.

between
center
end
end
import * as stylex from "@stylexjs/stylex"
import { HStack, VStack } from "@/components/ui/stack"
import { color, radius, space } from "@/theme/tokens.stylex"

const styles = stylex.create({
  row: {
    borderRadius: radius.lg,
    borderWidth: 1,
    borderStyle: "solid",
    padding: space.s2,
  },
  tall: {
    borderRadius: radius.md,
    backgroundColor: color.muted,
    paddingInline: space.s3,
    paddingBlock: space.s2,
  },
  short: {
    borderRadius: radius.md,
    backgroundColor: `color-mix(in oklab, ${color.muted} 40%, transparent)`,
    paddingInline: space.s3,
    paddingBlock: space.s1,
  },
})

export default function StackAlignment() {
  return (
    <VStack gap={3} width="20rem">
      <HStack justify="between" align="center" gap={2} xstyle={styles.row}>
        <div {...stylex.props(styles.tall)}>between</div>
        <div {...stylex.props(styles.short)}>center</div>
      </HStack>
      <HStack justify="end" align="end" gap={2} xstyle={styles.row}>
        <div {...stylex.props(styles.tall)}>end</div>
        <div {...stylex.props(styles.short)}>end</div>
      </HStack>
    </VStack>
  )
}

Spacing

Every spacing prop takes a step off the scale. Each step is 0.25rem times its number, so gap={3} is 0.75rem. An off-scale value is a type error.

0  0.5  1  1.5  2  2.5  3  3.5  4  5  6  8  10  12  16  24

Padding props resolve most-specific-first, per edge. An edge prop beats its axis prop, which beats padding.

<VStack padding={4} paddingBlockEnd={8} />

Sizing

width, height, maxWidth and minHeight take a number, read as pixels, or a CSS length string. Stack writes them to the element's inline style.

<VStack gap={4} maxWidth="28rem" />

Scrolling

Set scrollable on a flex child that has to scroll. It sets overflow: auto and the min-height: 0 the child needs, or its automatic minimum size holds it at content height and the scrollbar never appears. Pair it with grow.

<VStack height="100svh">
  <Header />
  <VStack grow scrollable>
    <LongContent />
  </VStack>
</VStack>

Composition

Use render to choose a semantic element.

Project

Choose where to continue.
import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card"
import { HStack, VStack } from "@/components/ui/stack"

export default function StackRender() {
  return (
    <Card render={<section aria-label="Project" />}>
      <CardHeader>
        <CardTitle render={<h3>Project</h3>} />
      </CardHeader>
      <CardContent>
        <VStack gap={3}>
          <span>Choose where to continue.</span>
          <HStack render={<nav aria-label="Project links" />} gap={4}>
            <a href="#usage">Usage</a>
            <a href="#api-reference">API reference</a>
          </HStack>
        </VStack>
      </CardContent>
    </Card>
  )
}

API reference

Pass render to replace a part's element or compose it with another component.

Stack

PropTypeDefault
direction"horizontal" | "vertical""vertical"
justify"start" | "center" | "end" | "between" | "around" | "evenly"—
align"start" | "center" | "end" | "stretch" | "baseline"—
gapSpacingStep—
paddingSpacingStep—
paddingInlineSpacingStep—
paddingInlineStartSpacingStep—
paddingInlineEndSpacingStep—
paddingBlockSpacingStep—
paddingBlockStartSpacingStep—
paddingBlockEndSpacingStep—
wrap"nowrap" | "wrap" | "wrap-reverse"—
growbooleanfalse
scrollablebooleanfalse
widthstring | number—
heightstring | number—
maxWidthstring | number—
minHeightstring | number—
xstyleStyleXStyles—
styleCSSProperties—
classNamestring—

Pass element-specific props on the render element, such as render={<Link to="/" />}. Use a type argument such as VStack<"fieldset"> when passing a fieldset ref.

HStack, VStack

Stack with direction fixed. They take every other Stack prop.

Data attributes

AttributeOnEffect
data-slot="stack"rootTargets the layout
data-orientationrootMirrors direction