# Stack

Lays out children in a vertical column.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Stack.tsx)

## Overview

Stack applies a spacing token `gap` between its children and stretches them to its width by default.

## Examples

### Basic

```tsx
import { Stack } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Stack gap="12">
      <span>Card content</span>
      <span>Second line</span>
    </Stack>
  )
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stack/Basic.tsx)

### Gap

Set `gap` to a spacing token. It defaults to `16`.

```tsx
import { Inline, Stack, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Inline align="start" gap="32" wrap>
      {(['4', '12', '24'] as const).map((gap) => (
        <Stack gap={gap} key={gap}>
          {[1, 2, 3].map((n) => (
            <span key={n} {...styles.chip()}>
              gap {gap}
            </span>
          ))}
        </Stack>
      ))}
    </Inline>
  )
}

namespace styles {
  export const chip = style({
    backgroundColor: 'container.regular',
    borderRadius: 'full',
    cornerShape: 'round',
    paddingBlock: '4',
    paddingInline: '12',
  })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stack/Gap.tsx)

### Align

Set `align` to `start`, `center`, `end`, or `stretch` (default).

```tsx
import { Inline, Stack, style } from '@tempoxyz/ds'

export function Demo() {
  return (
    <Inline align="start" gap="32" wrap>
      {(['start', 'center', 'end', 'stretch'] as const).map((align) => (
        <Stack align={align} gap="8" key={align} {...styles.column()}>
          <span {...styles.chip()}>{align}</span>
          <span {...styles.chip()}>Second line</span>
        </Stack>
      ))}
    </Inline>
  )
}

namespace styles {
  export const chip = style({
    backgroundColor: 'container.regular',
    borderRadius: 'full',
    cornerShape: 'round',
    paddingBlock: '4',
    paddingInline: '12',
  })

  export const column = style({ width: '10rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Stack/Align.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Stack } from '@tempoxyz/ds'

<Stack />
```

## Guidelines

### When to Use

* Space siblings vertically, such as form fields, settings sections, or cards in a column.
* Place a label above its value, such as Recipient over a 0x address.

### When Not to Use

* Use [Inline](/docs/components/inline) for a horizontal row.
* Use [Grid](/docs/components/grid) for collections in columns.
* Use [ListGroup](/docs/components/list-group) for a divided list of settings or details.

### Use Gap Instead of Margins

Space siblings with `gap`, not child margins. See [Layout](/docs/foundations/layout).

**Do:** Set one `gap` on the Stack.

```tsx
/** Do example for "Use Gap Instead of Margins" on the Stack page: set one `gap` on the Stack. @module */
import { Stack, style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Stack gap="12" {...styles.canvas()}>
      <Surface size="small">Balance</Surface>
      <Surface size="small">Activity</Surface>
      <Surface size="small">Access keys</Surface>
    </Stack>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })
}
```

**Don't:** Set margins on each child, which drift apart and leave space after the last one.

```tsx
/**
 * Don't example for "Use Gap Instead of Margins" on the Stack page.
 * Don't set margins on each child, which drift apart and leave space after the last one.
 * @module
 */
import { style, Surface } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.canvas()}>
      <Surface size="small" {...styles.first()}>
        Balance
      </Surface>
      <Surface size="small" {...styles.second()}>
        Activity
      </Surface>
      <Surface size="small" {...styles.third()}>
        Access keys
      </Surface>
    </div>
  )
}

namespace styles {
  export const canvas = style({
    backgroundColor: 'background.primary',
    borderRadius: 'sm',
    boxSizing: 'border-box',
    padding: '12',
    width: '100% !custom',
  })

  export const first = style({ marginBlockEnd: '4' })

  export const second = style({ marginBlockEnd: '24' })

  export const third = style({ marginBlockEnd: '16' })
}
```

### Choose Gap by Relationship

Nest stacks so the space inside a group is smaller than the space between groups, such as `4` between a label and its value and `24` between pairs.

**Do:** Nest stacks so each label sits closer to its own value.

```tsx
/**
 * Do example for "Choose Gap by Relationship" on the Stack page.
 * Nest stacks so each label sits closer to its own value.
 * @module
 */
import { Stack, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Stack gap="24" {...styles.column()}>
      <Stack gap="4">
        <span {...styles.label()}>Recipient</span>
        <span {...styles.value()}>0x71C7…976F</span>
      </Stack>
      <Stack gap="4">
        <span {...styles.label()}>Amount</span>
        <span {...styles.value()}>250.00 USDC</span>
      </Stack>
    </Stack>
  )
}

namespace styles {
  export const column = style({ width: '100% !custom' })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```

**Don't:** Space every item the same, which hides the groups.

```tsx
/**
 * Don't example for "Choose Gap by Relationship" on the Stack page.
 * Don't space every item the same, which hides the groups.
 * @module
 */
import { Stack, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Stack gap="16" {...styles.column()}>
      <span {...styles.label()}>Recipient</span>
      <span {...styles.value()}>0x71C7…976F</span>
      <span {...styles.label()}>Amount</span>
      <span {...styles.value()}>250.00 USDC</span>
    </Stack>
  )
}

namespace styles {
  export const column = style({ width: '100% !custom' })

  export const label = style({ color: 'content.secondary', typography: 'body.b3' })

  export const value = style({ color: 'content.primary', typography: 'body.b1Strong' })
}
```

## Accessibility

Stack adds no role, name, or keyboard behavior.

### Semantics

* **Element (div):** Carries no role by default.
* **Render (render):** Swaps in a semantic element, such as a nav for links, or a list so screen readers announce the count.

### Your Responsibilities

* **Match DOM and Visual Order (SC 1.3.2, SC 2.4.3):** Don't reorder children with CSS. [Reading](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html) and [focus](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) order follow the DOM.

## Related

[Inline](/docs/components/inline)

Use for horizontal rows.

[Grid](/docs/components/grid)

Use for columns of items.

[Separator](/docs/components/separator)

Use for a rule between groups.

[Layout](/docs/foundations/layout)

Covers the spacing scale.
