# Button

Ação principal e ações de apoio com o contrato copy-first ou 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/pagination.md

## 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/button`).

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

```tsx
import { Button } from '@/components/ui/button'

export function ButtonExample() {
  return (
    <div className="flex flex-col items-start gap-3">
      <Button variant="itps">Salvar</Button>
      <Button variant="itpsSecondary">Editar</Button>
      <Button variant="outline">Revisar</Button>
      <Button variant="ghost">Cancelar</Button>
    </div>
  )
}
```

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

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

<template>
  <div class="flex flex-col items-start gap-3">
    <Button variant="itps">Salvar</Button>
    <Button variant="itpsSecondary">Editar</Button>
    <Button variant="outline">Revisar</Button>
    <Button variant="ghost">Cancelar</Button>
  </div>
</template>
```

**HTML (copy-first)**

```html
<button type="button" class="itps-btn itps-btn--primary">Salvar</button>

<button type="button" class="itps-btn itps-btn--secondary">Editar</button>

<button type="button" class="itps-btn itps-btn--outline">Revisar</button>

<button type="button" class="itps-btn itps-btn--ghost">Cancelar</button>
```

## Instalação

O comando instala o Button Sinapse: as variantes do shadcn com o visual Sinapse em `default` e `secondary`, mais os aliases `itps` e `itpsSecondary`. Configure o registry uma vez por projeto em [Comece por aqui](/comecar).

**terminal · React/Next**

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

**terminal · Vue 3/Nuxt 4**

```sh
pnpm dlx shadcn-vue@latest add https://dsystem.sinapse.org.br/r/vue/button.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 Button para ações que executam uma operação no contexto atual, como salvar, editar, revisar ou cancelar. Para navegação entre páginas, use Link; a página Link cobre âncoras, CTAs em linha e composição `asChild`/`as-child`.

Em React/Next e Vue 3/Nuxt 4, use `variant="itps"` para a ação principal e `variant="itpsSecondary"` para a ação de apoio. Para HTML ou wrappers finos, aplique `itps-btn` com o modificador visual correspondente.

## Exemplos

### Variantes

| Uso | React/Next e Vue 3/Nuxt 4 | HTML |
|-----|--------------------------|------|
| Ação principal | `variant="itps"` | `itps-btn itps-btn--primary` |
| Ação de apoio | `variant="itpsSecondary"` | `itps-btn itps-btn--secondary` |
| Ação contornada | `variant="outline"` | `itps-btn itps-btn--outline` |
| Ação discreta | `variant="ghost"` | `itps-btn itps-btn--ghost` |

### Tamanhos

No Button gerado pelo shadcn, mantenha os tamanhos da stack. Nas classes copy-first, use `itps-btn--sm`, sem modificador para o padrão, ou `itps-btn--lg`.

### Estados

Use `disabled` para bloquear interação. Para carregamento, combine `disabled` e `aria-busy="true"`; quando houver spinner, mantenha o ícone decorativo com `aria-hidden="true"`.

### Ícones

Use ícones Tabler em todas as stacks: `@tabler/icons-react` em React/Next, `@tabler/icons-vue` em Vue 3/Nuxt 4 e as classes `ti ti-*` em HTML. Dentro do botão, o ícone é apoio visual: use `aria-hidden="true"` quando o texto já descreve a ação.

## API copy-first

| Classe/atributo | Uso |
|-----------------|-----|
| `itps-btn` | Classe base. Use sempre em botões copy-first. |
| `itps-btn itps-btn--primary` | Ação principal da tela ou do fluxo. |
| `itps-btn itps-btn--secondary` | Ação de apoio com menor peso visual. |
| `itps-btn itps-btn--outline` | Ação contornada ou alternativa. |
| `itps-btn itps-btn--ghost` | Ação discreta, geralmente secundária ao conteúdo. |
| `itps-btn--sm` | Botão compacto. Combine com `itps-btn` e uma variante. |
| `itps-btn--lg` | Botão de destaque. Combine com `itps-btn` e uma variante. |
| `disabled` | Bloqueia interação em `<button>`. |
| `aria-disabled="true"` | Indica estado indisponível quando o elemento não pode usar `disabled`. |
| `aria-busy="true"` | Comunica carregamento; use junto de `disabled` quando a ação está em andamento. |
| `type="button"` | Evita submit acidental em formulários. Troque para `submit` apenas quando o botão envia o formulário. |
| `aria-label` | Use somente em botões sem texto visível ou quando o texto não descreve a ação. |

## Acessibilidade

- Prefira texto visível que descreva a ação.
- Em botões só com ícone, use `aria-label`.
- Durante o carregamento, mantenha o botão desabilitado e anuncie o estado com `aria-busy="true"`.