HStack & VStack

Horizontal and vertical flex containers with gap.

Examples

Horizontal

One

Two

Three

<HStack align="center" gap={3}>
  <Card>
    <Text type="body">One</Text>
  </Card>
  <Card>
    <Text type="body">Two</Text>
  </Card>
  <Card>
    <Text type="body">Three</Text>
  </Card>
</HStack>

Vertical

One

Two

Three

<VStack gap={3}>
  <Card>
    <Text type="body">One</Text>
  </Card>
  <Card>
    <Text type="body">Two</Text>
  </Card>
  <Card>
    <Text type="body">Three</Text>
  </Card>
</VStack>

Gap Scale

gap=0

A

B

C

gap=1

A

B

C

gap=2

A

B

C

gap=3

A

B

C

gap=4

A

B

C

gap=6

A

B

C

gap=8

A

B

C

gap=10

A

B

C

<VStack gap={6}>
  {([0, 1, 2, 3, 4, 6, 8, 10] as StackGap[]).map(gap => (
    <VStack gap={1} key={gap}>
      <Text color="secondary" type="supporting">
        gap={String(gap)}
      </Text>
      <HStack gap={gap}>
        <Box>A</Box>
        <Box>B</Box>
        <Box>C</Box>
      </HStack>
    </VStack>
  ))}
</VStack>

Wrap

wrap

One

Two

Three

Four

Five

wrap-reverse

One

Two

Three

Four

Five

<VStack gap={4}>
  <VStack gap={1}>
    <Text color="secondary" type="supporting">
      wrap
    </Text>
    <HStack gap={2} width={240} wrap="wrap">
      <Box>One</Box>
      <Box>Two</Box>
      <Box>Three</Box>
      <Box>Four</Box>
      <Box>Five</Box>
    </HStack>
  </VStack>
  <VStack gap={1}>
    <Text color="secondary" type="supporting">
      wrap-reverse
    </Text>
    <HStack gap={2} width={240} wrap="wrap-reverse">
      <Box>One</Box>
      <Box>Two</Box>
      <Box>Three</Box>
      <Box>Four</Box>
      <Box>Five</Box>
    </HStack>
  </VStack>
</VStack>

Alignment

justify="between", align="center"

Start

Middle

End

justify="center", align="end"

A

B

<VStack gap={4}>
  <VStack gap={1}>
    <Text color="secondary" type="supporting">
      justify=&quot;between&quot;, align=&quot;center&quot;
    </Text>
    <HStack
      align="center"
      gap={2}
      height={80}
      justify="between"
      width={400}>
      <Box>Start</Box>
      <Box>Middle</Box>
      <Box>End</Box>
    </HStack>
  </VStack>
  <VStack gap={1}>
    <Text color="secondary" type="supporting">
      justify=&quot;center&quot;, align=&quot;end&quot;
    </Text>
    <HStack align="end" gap={2} height={80} justify="center" width={400}>
      <Box>A</Box>
      <Box>B</Box>
    </HStack>
  </VStack>
</VStack>

Polymorphic Element

Rendered as <nav>

Home

About

Contact

Rendered as <ul>
Item 1
Item 2

<VStack gap={4}>
  <VStack aria-label="Main navigation" as="nav" gap={2}>
    <Text type="supporting">Rendered as &lt;nav&gt;</Text>
    <HStack gap={2}>
      <Box>Home</Box>
      <Box>About</Box>
      <Box>Contact</Box>
    </HStack>
  </VStack>
  <VStack as="ul" gap={1} style={{listStyle: 'none', padding: 0}}>
    <Text type="supporting">Rendered as &lt;ul&gt;</Text>
    <Box>Item 1</Box>
    <Box>Item 2</Box>
  </VStack>
</VStack>

Explicit Size

Fixed 200×200

Content

50% × 10rem

Content

<HStack gap={4}>
  <VStack gap={2} height={200} width={200}>
    <Box>Fixed 200×200</Box>
    <Box>Content</Box>
  </VStack>
  <VStack gap={2} height="10rem" width="50%">
    <Box>50% × 10rem</Box>
    <Box>Content</Box>
  </VStack>
</HStack>

Nested

Top Left

Bottom Left

Top Right

Bottom Right

Footer Left

Footer Right

<VStack gap={4}>
  <HStack gap={3}>
    <VStack gap={2}>
      <Box>Top Left</Box>
      <Box>Bottom Left</Box>
    </VStack>
    <VStack gap={2}>
      <Box>Top Right</Box>
      <Box>Bottom Right</Box>
    </VStack>
  </HStack>
  <HStack gap={3}>
    <Box>Footer Left</Box>
    <Box>Footer Right</Box>
  </HStack>
</VStack>

API

HStack

A horizontal flex container that lays out children in a row with a consistent gap.

Prop	Type	Default	Description
align	"center" | "end" | "start" | "stretch"	—	Cross-axis alignment.
hAlign	"center" | "end" | "start" | "between" | "around" | "evenly"	—
justify	"center" | "end" | "start" | "between" | "around" | "evenly"	—	Main-axis alignment.
ref	Ref<HTMLElement>	—	Ref forwarded to the root element.
vAlign	"center" | "end" | "start" | "stretch"	—
children	ReactNode	—	Stack content.
as	ElementType	—	HTML element type to render.
data-testid	string	—	Test ID applied to the root element.
height	SizeValue	—	Fixed height. Numbers are treated as pixels.
width	SizeValue	—	Fixed width. Numbers are treated as pixels.
gap	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Gap between children.
wrap	"wrap" | "nowrap" | "wrap-reverse"	—	Flex wrap behavior.

VStack

A vertical flex container that lays out children in a column with a consistent gap.

Prop	Type	Default	Description
align	"center" | "end" | "start" | "stretch"	—	Cross-axis alignment.
hAlign	"center" | "end" | "start" | "stretch"	—
justify	"center" | "end" | "start" | "between" | "around" | "evenly"	—	Main-axis alignment.
ref	Ref<HTMLElement>	—	Ref forwarded to the root element.
vAlign	"center" | "end" | "start" | "between" | "around" | "evenly"	—
children	ReactNode	—	Stack content.
as	ElementType	—	HTML element type to render.
data-testid	string	—	Test ID applied to the root element.
height	SizeValue	—	Fixed height. Numbers are treated as pixels.
width	SizeValue	—	Fixed width. Numbers are treated as pixels.
gap	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Gap between children.
wrap	"wrap" | "nowrap" | "wrap-reverse"	—	Flex wrap behavior.