# Stack

Empilha os filhos numa direção, com o vão entre eles saído da escala da casa.

```tsx
<Stack gap="lg">
  <Field name="razao">…</Field>
  <Field name="cnpj">…</Field>
  <Stack direction="row" gap="sm" justify="end">
    <Button variant="secondary">Cancelar</Button>
    <Button>Salvar</Button>
  </Stack>
</Stack>
```

`direction` escolhe o eixo: `column`, o padrão, põe um embaixo do outro; `row`
põe lado a lado. `align` alinha no eixo cruzado e `justify` distribui no eixo
principal, com `between` empurrando o primeiro e o último para as pontas. `wrap`
deixa a linha quebrar quando os filhos não cabem, que é o caso de uma fileira
de selos ou de fichas.

## O vão é uma escala, e ela acompanha a densidade

`gap` não aceita pixel. São cinco passos, e mais `none`:

| Passo | Confortável | Compacta |
| ----- | ----------- | -------- |
| `xs`  | 4px         | 4px      |
| `sm`  | 8px         | 6px      |
| `md`  | 12px        | 8px      |
| `lg`  | 16px        | 12px     |
| `xl`  | 24px        | 16px     |

O padrão é `md`. Os passos saem dos tokens `--rc-gap-*`, que a densidade
reescreve junto com a altura de controle: a tela que passa para
`density="compact"` aperta também o vão entre os blocos, e não só os controles
dentro deles. Um `gap-3` escrito à mão fica com 12px nas duas.

`xs` não encolhe. Abaixo de 4px, selo encostado em selo vira uma palavra só.

## Outro elemento

`render` troca o elemento sem mudar o arranjo. Uma lista continua lista para o
leitor de tela, que anuncia quantos itens ela tem:

```tsx
<Stack render={<ul />} gap="sm">
  <li>Aula 1, concluída</li>
  <li>Aula 2, concluída</li>
</Stack>
```

## Quando não usar

- **Quando uma `div` com classe basta.** Dois elementos que se alinham uma vez,
  num lugar só, não pedem peça: `flex items-center gap-2` diz a mesma coisa. O
  `Stack` se paga onde o vão precisa seguir a densidade, ou onde a mesma
  arrumação se repete tela a tela e cada uma escolheria um número diferente.
- **Grade em duas dimensões.** Cartões que se arrumam em colunas e linhas são
  `Grid`, com `columns` ou `minItemWidth`. Um `Stack` com `wrap` quebra a linha,
  mas não alinha as colunas de uma linha com as da outra.
- **Moldura e respiro interno.** O `Stack` não desenha borda nem fundo. O bloco
  com moldura é o `Card`, e o topo da tela, com título e ações, é o
  `PageHeader`.
- **Duas áreas que a pessoa redimensiona.** Lista e detalhe com divisória que se
  arrasta são o `Splitter`.

## No React Native

Traduz: o `@rivocode/ui-native` exporta `Stack` - mesmas props, menos `render`; o vão é a escala confortável, porque no toque não há densidade compacta. A API não é a mesma do web (no nativo tudo é controlado), e a [tabela de paridade](/react-native) diz o que muda peça a peça.

## Importação

```tsx
import { Stack } from '@rivocode/ui'
```

## Exemplos

### Coluna de campos

```tsx
import { Badge, Button, Field, FieldLabel, Input, Stack } from '@rivocode/ui'

export function Column() {
  return (
    <Stack gap="lg" className="w-80">
      <Field name="curso">
        <FieldLabel>Nome do curso</FieldLabel>
        <Input defaultValue="Design de interfaces" />
      </Field>
      <Field name="carga">
        <FieldLabel>Carga horária</FieldLabel>
        <Input defaultValue="40 horas" />
      </Field>
      <Stack direction="row" gap="sm" justify="end">
        <Button variant="secondary">Cancelar</Button>
        <Button>Salvar</Button>
      </Stack>
    </Stack>
  )
}
```

### Linha que quebra

```tsx
import { Badge, Button, Field, FieldLabel, Input, Stack } from '@rivocode/ui'

const TAGS = ['Online', 'Iniciante', 'Com certificado', 'Turma de março', 'Aulas ao vivo às terças']

export function RowThatWraps() {
  return (
    <Stack direction="row" gap="xs" wrap className="w-72">
      {TAGS.map((tag) => (
        <Badge key={tag}>{tag}</Badge>
      ))}
    </Stack>
  )
}
```

### Título e ação nas pontas

```tsx
import { Badge, Button, Field, FieldLabel, Input, Stack } from '@rivocode/ui'

export function SpaceBetween() {
  return (
    <Stack direction="row" align="center" justify="between" className="w-96">
      <p className="text-base text-fg">Alunos da turma A</p>
      <Button size="sm" variant="secondary">
        Exportar
      </Button>
    </Stack>
  )
}
```

### Como lista

```tsx
import { Badge, Button, Field, FieldLabel, Input, Stack } from '@rivocode/ui'

export function AsList() {
  return (
    <Stack render={<ul />} gap="sm" className="w-64 text-base text-fg">
      <li>Aula 1, concluída</li>
      <li>Aula 2, concluída</li>
      <li>Aula 3, em andamento</li>
    </Stack>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `align` | `"baseline" \| "center" \| "end" \| "start" \| "stretch"` |  |  | - | O alinhamento no eixo cruzado. |
| `direction` | `"column" \| "row"` |  | `"column"` | - | O eixo dos filhos. |
| `gap` | `"lg" \| "md" \| "none" \| "sm" \| "xl" \| "xs"` |  | `"md"` | - | O vao entre os filhos, na escala da casa: `xs` 4, `sm` 8, `md` 12, `lg` 16 e `xl` 24 pixels na densidade confortavel. |
| `justify` | `"between" \| "center" \| "end" \| "start"` |  |  | - | A distribuicao no eixo principal. |
| `render` | `ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | - | Troca o elemento renderizado mantendo o arranjo: `<Stack render={<ul />}>`, `<Stack render={<nav />}>`. |
| `wrap` | `boolean` |  | `false` | - | Deixa os filhos quebrarem linha quando nao cabem. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Accordion](/componentes/accordion.md)
- [Affix](/componentes/affix.md)
- [AppShell](/componentes/app-shell.md)
- [AspectRatio](/componentes/aspect-ratio.md)
- [Avatar](/componentes/avatar.md)
- [Card](/componentes/card.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
