# Chip

Controle compacto para filtro, seleção, remoção ou atalho.

> 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: Data Display
- Status: stable

## 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 (`toggle-group`) 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 {
  ToggleGroup,
  ToggleGroupItem,
} from '@/components/ui/toggle-group'

export function ChipFilterExample() {
  return (
    <ToggleGroup type="multiple" defaultValue={['cardiologia']}>
      <ToggleGroupItem value="cardiologia">Cardiologia</ToggleGroupItem>
      <ToggleGroupItem value="neurologia">Neurologia</ToggleGroupItem>
      <ToggleGroupItem value="pediatria">Pediatria</ToggleGroupItem>
    </ToggleGroup>
  )
}
```

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

```vue
<script setup lang="ts">
import {
  ToggleGroup,
  ToggleGroupItem,
} from '@/components/ui/toggle-group'
</script>

<template>
  <ToggleGroup type="multiple" :default-value="['cardiologia']">
    <ToggleGroupItem value="cardiologia">Cardiologia</ToggleGroupItem>
    <ToggleGroupItem value="neurologia">Neurologia</ToggleGroupItem>
    <ToggleGroupItem value="pediatria">Pediatria</ToggleGroupItem>
  </ToggleGroup>
</template>
```

**HTML (copy-first)**

```html
<div class="flex flex-wrap items-center gap-2" role="group" aria-label="Especialidades">
  <button type="button" class="itps-chip is-selected" aria-pressed="true" aria-label="Remover filtro Cardiologia">
    <span class="itps-chip__label">Cardiologia</span>
    <span class="itps-chip__separator" aria-hidden="true"></span>
    <i class="itps-chip__dismiss ti ti-x" aria-hidden="true"></i>
  </button>
  <button type="button" class="itps-chip" aria-pressed="false">
    <span class="itps-chip__label">Neurologia</span>
  </button>
  <button type="button" class="itps-chip" aria-pressed="false">
    <span class="itps-chip__label">Pediatria</span>
  </button>
</div>
```

## Instalação

O comando instala o Toggle Group 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/chip
```

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/chip.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

Em React/Next com shadcn/ui e Vue 3/Nuxt 4 com shadcn-vue, use `ToggleGroup` quando o Chip representa filtros ou seleção rápida.

Para HTML ou wrappers finos, use `itps-chip` em elementos semânticos: `<button>` para ação/seleção e `<a>` somente quando houver navegação.

## Exemplos

### Estrutura

| Peça | React/Next e Vue 3/Nuxt 4 | HTML |
|------|--------------------------|------|
| Grupo | `ToggleGroup` | `role="group"` quando os chips formam um conjunto |
| Item | `ToggleGroupItem` | `itps-chip` em `button` ou `a` |
| Estado selecionado | valor do grupo | `is-selected` e `aria-pressed="true"` |
| Rótulo | conteúdo do item | `itps-chip__label` |
| Ícone | ícone decorativo no conteúdo | `itps-chip__icon` ou `itps-chip__dismiss` |

### Composições copy-first

Use a composição copy-first quando o chip precisa remover filtro, navegar, mostrar ícone contextual ou comunicar indisponibilidade.

**HTML (copy-first)**

```html
<div class="flex flex-wrap items-center gap-2">
  <button type="button" class="itps-chip is-selected" aria-pressed="true" aria-label="Remover filtro SUS">
    <span class="itps-chip__label">SUS</span>
    <span class="itps-chip__separator" aria-hidden="true"></span>
    <i class="itps-chip__dismiss ti ti-x" aria-hidden="true"></i>
  </button>
  <button type="button" class="itps-chip">
    <i class="itps-chip__icon ti ti-filter" aria-hidden="true"></i>
    <span class="itps-chip__label">Filtros</span>
  </button>
  <a href="/pacientes?status=ativo" class="itps-chip">
    <i class="itps-chip__icon ti ti-filter" aria-hidden="true"></i>
    <span class="itps-chip__label">Ver pacientes ativos</span>
  </a>
  <button type="button" class="itps-chip is-disabled" disabled>
    <span class="itps-chip__label">Indisponível</span>
  </button>
  <a class="itps-chip is-disabled" aria-disabled="true" tabindex="-1">
    <span class="itps-chip__label">Histórico</span>
  </a>
</div>
```

## API copy-first

| Classe/atributo | Uso |
|-----------------|-----|
| `itps-chip` | Base visual para chip compacto. |
| `is-selected` | Estado visual selecionado. Combine com `aria-pressed="true"`. |
| `is-disabled` | Estado visual indisponível. Combine com `disabled` ou `aria-disabled`. |
| `itps-chip__label` | Texto do chip com truncamento seguro. |
| `itps-chip__icon` | Ícone decorativo de contexto. |
| `itps-chip__separator` | Divisor antes do ícone de remoção em chip selecionado. |
| `itps-chip__dismiss` | Ícone decorativo de remoção. |
| `aria-pressed` | Expõe seleção em chips de filtro. |
| `aria-label` | Nome acessível específico quando o texto visível não descreve a ação. |
| `aria-disabled`, `tabindex="-1"` | Mantêm links indisponíveis fora da ordem de foco. |

## Acessibilidade

Use `<button>` quando o chip executa uma ação, alterna seleção ou remove filtro. Use `<a>` apenas quando o destino for navegação.

Chips selecionados devem expor estado com `aria-pressed`; chips com remoção implícita precisam de `aria-label` específico. Em botão indisponível, use `disabled`. Em link indisponível, remova `href`, exponha `aria-disabled="true"` e tire da ordem de foco com `tabindex="-1"`.