# Tag

Indicador somente leitura para estado, classificação ou rótulo curto.

> 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: Componente Sinapse, com as variantes desta página (`add @sinapse/tag`).

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

```tsx
import { Tag } from '@/components/ui/tag'

export function TagExample() {
  return (
    <Tag variant="success">Aprovado</Tag>
  )
}
```

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

```vue
<script setup lang="ts">
import { Tag } from '@/components/ui/tag'
</script>

<template>
  <Tag variant="success">Aprovado</Tag>
</template>
```

**HTML (copy-first)**

```html
<span class="itps-tag itps-tag--success itps-tag--sm">
  <span>Aprovado</span>
</span>
```

## Instalação

O comando instala o componente `Tag` do Sinapse, com as mesmas variantes do HTML. Não é o Badge do shadcn. Configure o registry uma vez por projeto em [Comece por aqui](/comecar).

**terminal · React/Next**

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

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/tag.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 `Tag` para rótulos curtos e somente leitura. Reserve ações clicáveis para Button, Link ou Chip.

Para HTML ou wrappers finos, use `itps-tag` com modificadores semânticos. Tag comunica estado ou classificação curta; não executa ação e não deve receber foco.

## Exemplos

### Estrutura

| Peça | React/Next e Vue 3/Nuxt 4 | HTML |
|------|--------------------------|------|
| Raiz | `Tag` | `itps-tag` |
| Variante | `variant`: `default`, `success`, `alert`, `danger`, `disabled` | `itps-tag--default`, `itps-tag--success`, `itps-tag--alert`, `itps-tag--danger`, `itps-tag--disabled` |
| Tamanho | `size`: `xs`, `sm` (padrão), `md`, `lg` | `itps-tag--xs`, `itps-tag--sm`, `itps-tag--md`, `itps-tag--lg` |
| Ícone | ícone Tabler no conteúdo, com `aria-hidden="true"` | `itps-tag__icon` com `aria-hidden="true"` |

### Variações copy-first

Use a variante semântica que descreve o estado da entidade. `sm` é o tamanho padrão; ajuste apenas quando a densidade da interface pedir.

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

```tsx
import { IconAlertCircle, IconCircleCheck, IconClock } from '@tabler/icons-react'

import { Tag } from '@/components/ui/tag'

export function TagVariants() {
  return (
    <div className="grid gap-4">
      <div className="flex flex-wrap items-center gap-2">
        <Tag>Em análise</Tag>
        <Tag variant="success">Aprovado</Tag>
        <Tag variant="alert">Atenção</Tag>
        <Tag variant="danger">Crítico</Tag>
        <Tag variant="disabled" aria-disabled="true">Arquivado</Tag>
      </div>
      <div className="flex flex-wrap items-center gap-2">
        <Tag size="xs">Extra pequeno</Tag>
        <Tag size="md">Médio</Tag>
        <Tag size="lg">Grande</Tag>
      </div>
      <div className="flex flex-wrap items-center gap-2">
        <Tag variant="success"><IconCircleCheck aria-hidden="true" />Pago</Tag>
        <Tag variant="alert"><IconClock aria-hidden="true" />Pendente</Tag>
        <Tag variant="danger"><IconAlertCircle aria-hidden="true" />Vencido</Tag>
      </div>
    </div>
  )
}
```

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

```vue
<script setup lang="ts">
import { IconAlertCircle, IconCircleCheck, IconClock } from '@tabler/icons-vue'

import { Tag } from '@/components/ui/tag'
</script>

<template>
  <div class="grid gap-4">
    <div class="flex flex-wrap items-center gap-2">
      <Tag>Em análise</Tag>
      <Tag variant="success">Aprovado</Tag>
      <Tag variant="alert">Atenção</Tag>
      <Tag variant="danger">Crítico</Tag>
      <Tag variant="disabled" aria-disabled="true">Arquivado</Tag>
    </div>
    <div class="flex flex-wrap items-center gap-2">
      <Tag size="xs">Extra pequeno</Tag>
      <Tag size="md">Médio</Tag>
      <Tag size="lg">Grande</Tag>
    </div>
    <div class="flex flex-wrap items-center gap-2">
      <Tag variant="success"><IconCircleCheck aria-hidden="true" />Pago</Tag>
      <Tag variant="alert"><IconClock aria-hidden="true" />Pendente</Tag>
      <Tag variant="danger"><IconAlertCircle aria-hidden="true" />Vencido</Tag>
    </div>
  </div>
</template>
```

**HTML (copy-first)**

```html
<div class="grid gap-4">
  <div class="flex flex-wrap items-center gap-2">
    <span class="itps-tag itps-tag--default itps-tag--sm">
      <span>Em análise</span>
    </span>
    <span class="itps-tag itps-tag--success itps-tag--sm">
      <span>Aprovado</span>
    </span>
    <span class="itps-tag itps-tag--alert itps-tag--sm">
      <span>Atenção</span>
    </span>
    <span class="itps-tag itps-tag--danger itps-tag--sm">
      <span>Crítico</span>
    </span>
    <span class="itps-tag itps-tag--disabled itps-tag--sm" aria-disabled="true">
      <span>Arquivado</span>
    </span>
  </div>

  <div class="flex flex-wrap items-center gap-2">
    <span class="itps-tag itps-tag--default itps-tag--xs">
      <span>Extra pequeno</span>
    </span>
    <span class="itps-tag itps-tag--default itps-tag--md">
      <span>Médio</span>
    </span>
    <span class="itps-tag itps-tag--default itps-tag--lg">
      <span>Grande</span>
    </span>
  </div>

  <div class="flex flex-wrap items-center gap-2">
    <span class="itps-tag itps-tag--success itps-tag--sm">
      <i class="itps-tag__icon ti ti-circle-check" aria-hidden="true"></i>
      <span>Pago</span>
    </span>
    <span class="itps-tag itps-tag--alert itps-tag--sm">
      <i class="itps-tag__icon ti ti-clock" aria-hidden="true"></i>
      <span>Pendente</span>
    </span>
    <span class="itps-tag itps-tag--danger itps-tag--sm">
      <i class="itps-tag__icon ti ti-alert-circle" aria-hidden="true"></i>
      <span>Vencido</span>
    </span>
  </div>
</div>
```

## API copy-first

| Classe/atributo | Uso |
|-----------------|-----|
| `itps-tag` | Wrapper somente leitura do rótulo. |
| `itps-tag--default` | Estado neutro ou informativo. |
| `itps-tag--success` | Estado positivo, concluído ou aprovado. |
| `itps-tag--alert` | Estado de atenção ou pendência. |
| `itps-tag--danger` | Estado crítico, erro ou risco alto. |
| `itps-tag--disabled` | Estado arquivado ou indisponível. |
| `itps-tag--xs`, `itps-tag--sm`, `itps-tag--md`, `itps-tag--lg` | Tamanhos por densidade. |
| `itps-tag__icon` | Ícone decorativo que reforça o texto. |
| `aria-disabled="true"` | Expõe estado indisponível quando necessário. |
| `aria-hidden="true"` | Esconde ícones decorativos de tecnologias assistivas. |

## Acessibilidade

Renderize como `<span>` para manter o comportamento somente leitura. Não use `button`, `a`, `tabindex` ou handlers de clique em Tag.

O texto deve ser suficiente para explicar o estado; ícone é decorativo. Use `aria-disabled="true"` apenas quando precisar comunicar estado arquivado ou indisponível para tecnologias assistivas.