# Breadcrumb

Navegação hierárquica horizontal com página atual e composição shadcn.

> Documentação do Sinapse DS. Snippets shadcn usam os componentes do seu projeto (`@/components/ui/*`); snippets HTML usam as classes `itps-*` do CSS Sinapse (`/css/<versão>/`, veja `/comecar.md`). Componentes do site de documentação não fazem parte do DS.

- Categoria: Ações & Navegação
- Status: stable
- Relacionados: /componentes/link.md, /componentes/tabs.md

## Em cada stack

- HTML e Astro: Classes `itps-*` do CSS Sinapse, com todas as variantes desta página.
- React e Vue: Componentes padrão do shadcn (`breadcrumb`) com o tema Sinapse: cores, fonte e raio vêm do tema, e as variantes `itps-*` desta página existem só no HTML.

**React/Next (shadcn/ui)**

```tsx
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@/components/ui/breadcrumb'

export function BreadcrumbExample() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/">Início</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="/componentes">Componentes</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

**Vue 3/Nuxt 4 (shadcn-vue)**

```vue
<script setup lang="ts">
import {
  Breadcrumb,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@/components/ui/breadcrumb'
</script>

<template>
  <Breadcrumb>
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="/">Início</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbLink href="/componentes">Componentes</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
      </BreadcrumbItem>
    </BreadcrumbList>
  </Breadcrumb>
</template>
```

**HTML (copy-first)**

```html
<nav class="itps-breadcrumb" aria-label="Trilha de navegação">
  <ol class="itps-breadcrumb__list">
    <li class="itps-breadcrumb__item">
      <a class="itps-breadcrumb__link" href="/">Início</a>
    </li>
    <li class="itps-breadcrumb__separator" aria-hidden="true">
      <i class="ti ti-chevron-right"></i>
    </li>
    <li class="itps-breadcrumb__item">
      <a class="itps-breadcrumb__link" href="/componentes">Componentes</a>
    </li>
    <li class="itps-breadcrumb__separator" aria-hidden="true">
      <i class="ti ti-chevron-right"></i>
    </li>
    <li class="itps-breadcrumb__item">
      <span class="itps-breadcrumb__page" aria-current="page">Breadcrumb</span>
    </li>
  </ol>
</nav>
```

## Instalação

O comando instala o Breadcrumb da sua stack com o tema Sinapse. Configure o registry uma vez por projeto em [Comece por aqui](/comecar).

**terminal · React/Next**

```sh
pnpm dlx shadcn@latest add @sinapse/breadcrumb
```

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/breadcrumb.json
```

Sem shadcn, não há instalação por componente: use o CSS Sinapse e as classes da API copy-first desta página.

## Uso

Use Breadcrumb quando o usuário precisa entender a hierarquia entre a raiz e a página atual. Ele é navegação auxiliar, não substitui o menu principal.

Em React/Next com shadcn/ui e Vue 3/Nuxt 4 com shadcn-vue, use os componentes compostos de `@/components/ui/breadcrumb`. Para HTML ou wrappers finos, use `itps-breadcrumb` com lista ordenada, links navegáveis e página atual marcada por `aria-current="page"`.

## Exemplos

### Estrutura

| Peça | React/Next e Vue 3/Nuxt 4 | HTML |
|------|--------------------------|------|
| Landmark | `Breadcrumb` | `<nav class="itps-breadcrumb">` |
| Lista | `BreadcrumbList` | `itps-breadcrumb__list` |
| Item | `BreadcrumbItem` | `itps-breadcrumb__item` |
| Link | `BreadcrumbLink` | `itps-breadcrumb__link` |
| Página atual | `BreadcrumbPage` | `itps-breadcrumb__page` + `aria-current="page"` |
| Separador | `BreadcrumbSeparator` | `itps-breadcrumb__separator` |
| Colapso | `BreadcrumbEllipsis` | `itps-breadcrumb__ellipsis` |

### Colapso e raiz com ícone

Use a raiz com ícone quando ela melhora reconhecimento rápido. Para caminhos longos, substitua níveis intermediários por reticências e conecte o botão a um menu ou drawer da sua stack.

**React/Next (shadcn/ui)**

```tsx
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@/components/ui/breadcrumb'

export function BreadcrumbCollapsed() {
  return (
    <Breadcrumb>
      <BreadcrumbList>
        <BreadcrumbItem>
          <BreadcrumbLink href="/">Início</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbEllipsis />
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbLink href="/componentes">Componentes</BreadcrumbLink>
        </BreadcrumbItem>
        <BreadcrumbSeparator />
        <BreadcrumbItem>
          <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
        </BreadcrumbItem>
      </BreadcrumbList>
    </Breadcrumb>
  )
}
```

**Vue 3/Nuxt 4 (shadcn-vue)**

```vue
<script setup lang="ts">
import {
  Breadcrumb,
  BreadcrumbEllipsis,
  BreadcrumbItem,
  BreadcrumbLink,
  BreadcrumbList,
  BreadcrumbPage,
  BreadcrumbSeparator,
} from '@/components/ui/breadcrumb'
</script>

<template>
  <Breadcrumb>
    <BreadcrumbList>
      <BreadcrumbItem>
        <BreadcrumbLink href="/">Início</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbEllipsis />
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbLink href="/componentes">Componentes</BreadcrumbLink>
      </BreadcrumbItem>
      <BreadcrumbSeparator />
      <BreadcrumbItem>
        <BreadcrumbPage>Breadcrumb</BreadcrumbPage>
      </BreadcrumbItem>
    </BreadcrumbList>
  </Breadcrumb>
</template>
```

**HTML (copy-first)**

```html
<nav class="itps-breadcrumb" aria-label="Trilha de navegação compacta">
  <ol class="itps-breadcrumb__list">
    <li class="itps-breadcrumb__item">
      <a class="itps-breadcrumb__link" href="/">
        <i class="ti ti-home" aria-hidden="true"></i>
        <span>Início</span>
      </a>
    </li>
    <li class="itps-breadcrumb__separator" aria-hidden="true">
      <i class="ti ti-chevron-right"></i>
    </li>
    <li class="itps-breadcrumb__item">
      <button type="button" class="itps-breadcrumb__ellipsis" aria-label="Mostrar níveis intermediários">
        <i class="ti ti-dots" aria-hidden="true"></i>
      </button>
    </li>
    <li class="itps-breadcrumb__separator" aria-hidden="true">
      <i class="ti ti-chevron-right"></i>
    </li>
    <li class="itps-breadcrumb__item">
      <a class="itps-breadcrumb__link" href="/componentes">Componentes</a>
    </li>
    <li class="itps-breadcrumb__separator" aria-hidden="true">
      <i class="ti ti-chevron-right"></i>
    </li>
    <li class="itps-breadcrumb__item">
      <span class="itps-breadcrumb__page" aria-current="page">Breadcrumb</span>
    </li>
  </ol>
</nav>
```

## API copy-first

| Classe/atributo | Uso |
|-----------------|-----|
| `itps-breadcrumb` | Landmark de navegação auxiliar. |
| `itps-breadcrumb__list` | Lista ordenada flexível com quebra de linha. |
| `itps-breadcrumb__item` | Item da trilha. |
| `itps-breadcrumb__link` | Link navegável para níveis anteriores. |
| `itps-breadcrumb__page` | Página atual sem link. |
| `itps-breadcrumb__separator` | Separador decorativo entre itens. |
| `itps-breadcrumb__ellipsis` | Ação compacta para revelar níveis intermediários. |
| `aria-label` | Nomeia o landmark e botões sem texto visível suficiente. |
| `aria-current="page"` | Marca apenas a página atual. |
| `aria-hidden="true"` | Esconde separadores e ícones decorativos de tecnologias assistivas. |

## Acessibilidade

Use `nav` com `aria-label="Trilha de navegação"` e mantenha a trilha em `ol`, porque a ordem comunica hierarquia. Separadores e ícones decorativos devem usar `aria-hidden="true"`. Apenas o último item deve receber `aria-current="page"`. Se as reticências abrirem um menu, use um `button` real com nome acessível e conecte-o ao menu da sua stack.