# Stack

Children in a column or a row with the same space between each. A row runs in the reading direction, so it reverses itself in a right-to-left page, and `start` and `end` are the reading direction's.

- Registry name: `stack` (`@candor/stack`)
- Tier: Pro. Installing it needs a Pro, Premium or Team licence key: the person runs `npx candor-ui key <key>` themselves; never ask for the key in chat or write it to a file.
- Docs: https://candor.themethodic.com/docs/stack

## Install

```bash
npx candor-ui add stack
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/stack`.
It brings in: tokens, utils.
npm packages: @base-ui/react@^1.9.0.

## Example

```tsx
"use client"

import { Stack } from "@/components/candor/stack"
import { Button } from "@/components/candor/ui/button"
import { Text } from "@/components/candor/text"

export default function Example() {
  return (
    <Stack gap={4} className="max-w-md">
      <Stack gap={1}>
        <Text weight="semibold">Archive 214 stale leads?</Text>
        <Text tone="muted" size="sm">
          They move to the archive and can be restored for 30 days.
        </Text>
      </Stack>
      <Stack direction="row" gap={2} justify="end" wrap>
        <Button variant="outline">Cancel</Button>
        <Button>Archive</Button>
      </Stack>
    </Stack>
  )
}
```

## <Stack>

Props:

- `gap?: StackGap | undefined` (default `2`): The space between children, a step of the spacing scale that follows `data-density`. Default `2`.
- `direction?: "column" | "row" | undefined` (default `"column"`): `column` (the default) stacks the children; `row` lines them up in the reading direction.
- `align?: keyof typeof aligns | undefined`: How the children sit across the stack: for a row, `center` or `baseline` lines up text of different sizes.
- `justify?: keyof typeof justifies | undefined`: How the children share the stack's length: `between` pushes the first and last to the ends.
- `wrap?: boolean | undefined` (default `false`): Lets a row's children move onto a new line when they don't fit.
- `render?: useRender.RenderProp | undefined`: The element to draw instead of a `<div>`: `render={<ul />}` for a list, `render={<section />}`.
- `className?: string | undefined`: Classes for the element, applied last, so they win over the props.
- `children?: React.ReactNode | undefined`: What to stack.

Also takes the props of `React.ComponentProps<"div">`.

## Values

### stackGaps

Each gap's class. The gaps are steps of `--cd-control-gap`, the space between a control's parts, so they follow `data-density` (three quarters as wide compact, a quarter wider spacious) and a theme that sets it; at the default density they are Tailwind's `gap-1` to `gap-8`.

```ts
const stackGaps: Record<StackGap, string>
```

## Types

### StackGap

A step of the spacing scale: `4` is 1rem at the default density.

```ts
0 | 1 | 2 | 3 | 4 | 6 | 8
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider`: its fixed strings in `strings`, its nouns in `nouns`; entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.