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>

Padding

padding={6}

One

Two

Three

function Box({children}: {children: React.ReactNode}) {
  return (
    <VStack className={boxStyle} padding={3}>
      <Text type="body">{children}</Text>
    </VStack>
  );
}

<VStack className={boxStyle} gap={2} padding={6} width="fit-content">
  <Text color="secondary" type="supporting">
    padding=&#123;6&#125;
  </Text>
  <HStack gap={2}>
    <Box>One</Box>
    <Box>Two</Box>
    <Box>Three</Box>
  </HStack>
</VStack>

Axis And Edge Padding

paddingBlock={2} paddingInline={6}

Axis padding

padding={3} paddingBlockEnd={10}

Room for a scroll fade

padding={3} paddingInline={2} paddingInlineStart={8}

Aligned with a gutter

function Box({children}: {children: React.ReactNode}) {
  return (
    <VStack className={boxStyle} padding={3}>
      <Text type="body">{children}</Text>
    </VStack>
  );
}

<HStack align="start" gap={4} wrap="wrap">
  <VStack
    className={boxStyle}
    gap={2}
    paddingBlock={2}
    paddingInline={6}
    width="fit-content">
    <Text color="secondary" type="supporting">
      paddingBlock=&#123;2&#125; paddingInline=&#123;6&#125;
    </Text>
    <Box>Axis padding</Box>
  </VStack>
  <VStack
    className={boxStyle}
    gap={2}
    padding={3}
    paddingBlockEnd={10}
    width="fit-content">
    <Text color="secondary" type="supporting">
      padding=&#123;3&#125; paddingBlockEnd=&#123;10&#125;
    </Text>
    <Box>Room for a scroll fade</Box>
  </VStack>
  <VStack
    className={boxStyle}
    gap={2}
    padding={3}
    paddingInline={2}
    paddingInlineStart={8}
    width="fit-content">
    <Text color="secondary" type="supporting">
      padding=&#123;3&#125; paddingInline=&#123;2&#125;
      paddingInlineStart=&#123;8&#125;
    </Text>
    <Box>Aligned with a gutter</Box>
  </VStack>
</HStack>

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

function Box({children}: {children: React.ReactNode}) {
  return (
    <VStack className={boxStyle} padding={3}>
      <Text type="body">{children}</Text>
    </VStack>
  );
}

<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

function Box({children}: {children: React.ReactNode}) {
  return (
    <VStack className={boxStyle} padding={3}>
      <Text type="body">{children}</Text>
    </VStack>
  );
}

<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

function Box({children}: {children: React.ReactNode}) {
  return (
    <VStack className={boxStyle} padding={3}>
      <Text type="body">{children}</Text>
    </VStack>
  );
}

<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

function Box({children}: {children: React.ReactNode}) {
  return (
    <VStack className={boxStyle} padding={3}>
      <Text type="body">{children}</Text>
    </VStack>
  );
}

<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

function Box({children}: {children: React.ReactNode}) {
  return (
    <VStack className={boxStyle} padding={3}>
      <Text type="body">{children}</Text>
    </VStack>
  );
}

<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

function Box({children}: {children: React.ReactNode}) {
  return (
    <VStack className={boxStyle} padding={3}>
      <Text type="body">{children}</Text>
    </VStack>
  );
}

<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" | "start" | "end" | "stretch"	—	Cross-axis alignment.
hAlign	"center" | "start" | "end" | "between" | "around" | "evenly"	—
justify	"center" | "start" | "end" | "between" | "around" | "evenly"	—	Main-axis alignment.
ref	Ref<HTMLElement>	—	Ref forwarded to the root element.
vAlign	"center" | "start" | "end" | "stretch"	—
children	ReactNode	—	Stack content.
data-testid	string	—	Test ID applied to the root element.
as	ElementType	—	HTML element type to render.
width	SizeValue	—	Fixed width. Numbers are pixels, strings are used as-is.
height	SizeValue	—	Fixed height. Numbers are pixels, strings are used as-is.
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.
padding	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Inner padding step applied to every edge.
paddingBlock	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for both block edges (top and bottom in horizontal writing modes). Overrides padding on those edges.
paddingBlockEnd	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for the block-end edge. Overrides paddingBlock and padding.
paddingBlockStart	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for the block-start edge. Overrides paddingBlock and padding.
paddingInline	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for both inline edges (left and right in horizontal writing modes). Overrides padding on those edges.
paddingInlineEnd	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for the inline-end edge. Overrides paddingInline and padding.
paddingInlineStart	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for the inline-start edge. Overrides paddingInline and padding.

VStack

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

Prop	Type	Default	Description
align	"center" | "start" | "end" | "stretch"	—	Cross-axis alignment.
hAlign	"center" | "start" | "end" | "stretch"	—
justify	"center" | "start" | "end" | "between" | "around" | "evenly"	—	Main-axis alignment.
ref	Ref<HTMLElement>	—	Ref forwarded to the root element.
vAlign	"center" | "start" | "end" | "between" | "around" | "evenly"	—
children	ReactNode	—	Stack content.
data-testid	string	—	Test ID applied to the root element.
as	ElementType	—	HTML element type to render.
width	SizeValue	—	Fixed width. Numbers are pixels, strings are used as-is.
height	SizeValue	—	Fixed height. Numbers are pixels, strings are used as-is.
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.
padding	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Inner padding step applied to every edge.
paddingBlock	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for both block edges (top and bottom in horizontal writing modes). Overrides padding on those edges.
paddingBlockEnd	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for the block-end edge. Overrides paddingBlock and padding.
paddingBlockStart	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for the block-start edge. Overrides paddingBlock and padding.
paddingInline	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for both inline edges (left and right in horizontal writing modes). Overrides padding on those edges.
paddingInlineEnd	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for the inline-end edge. Overrides paddingInline and padding.
paddingInlineStart	0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10	—	Padding step for the inline-start edge. Overrides paddingInline and padding.