# CheckboxCard

Opção em cartão que se marca e desmarca: avisos, módulos do plano, adicionais.

É um `Checkbox` inteiro dentro de um cartão, com `title`, `description` e
`icon`, como o `RadioCard`. O cartão todo é o alvo, o `title` é o nome falado e
a `description` é a descrição da caixa. Marcado, a borda vai para o acento, e
a caixa com o tique continua lá.

Dentro de um `CheckboxGroup`, cada cartão leva o `value` e o grupo guarda a
lista marcada. Sozinho, ele fala `checked` e `onCheckedChange`, como o
`Checkbox`.

```tsx
<CheckboxGroup aria-label="Avisos de vencimento" defaultValue={["email"]}>
  <CheckboxCard value="email" title="E-mail" description="Um resumo por dia, às 8h." />
  <CheckboxCard value="sms" title="SMS" description="Só o que vence hoje." />
</CheckboxGroup>
```

`className` veste o cartão, e `classNames` alcança `card`, `control`, `icon`,
`title` e `description`, os mesmos nomes do `RadioCard`.

## Quando não usar

Quando só uma opção vale, é `RadioCard`: caixa de marcar promete que dá para
somar. Liga e desliga que vale na hora, sem botão de salvar, é `Switch`. E a
lista de opções curtas, sem nada a explicar, fica menor e mais rápida de ler
como `Checkbox` no `CheckboxGroup`.

## No React Native

Traduz pelo nome e pelas partes do web: `title`, `description`, `icon`, `indeterminate`, `disabled`, `invalid` e `classNames` (`card`, `control`, `icon`, `title`, `description`). É controlado por `checked` e `onCheckedChange`, como o `Checkbox` nativo, e o cartão inteiro é o alvo do toque, com papel `checkbox` e o estado (`mixed` no indeterminado).

**`media` é a área livre de cima, e só existe aqui.** Até a 5.0 o cartão do nativo era só o desenho do item do `CheckboxGroup variant="card"`, e não havia onde pôr um desenho grande: o `icon` cabe em 20pt, e escolher pelo desenho - a foto do produto, a amostra do tema - foi o pedido de um app real. `media` ocupa a largura do cartão, em cima do texto, e fica escondida do leitor de tela, que ouve o `title`.

Agrupe os cartões numa `View` e diga o nome do conjunto nela; o `CheckboxGroup variant="card"` continua sendo o atalho quando as opções vêm de uma lista e não precisam de desenho grande.

## Importação

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

## Exemplos

### Avisos de vencimento

```tsx
import { CheckboxCard, CheckboxGroup } from '@rivocode/ui'
import { Mail, MessageSquare } from 'lucide-react'

export function DueNotices() {
  return (
    <CheckboxGroup aria-label="Avisos de vencimento" defaultValue={['email']} className="w-full max-w-80">
      <CheckboxCard
        value="email"
        title="E-mail"
        description="Um resumo por dia, às 8h."
        icon={<Mail size={18} />}
      />
      <CheckboxCard
        value="sms"
        title="SMS"
        description="Só o que vence hoje."
        icon={<MessageSquare size={18} />}
      />
    </CheckboxGroup>
  )
}
```

### Sozinho

```tsx
import { CheckboxCard, CheckboxGroup } from '@rivocode/ui'
import { Mail, MessageSquare } from 'lucide-react'

export function Alone() {
  return (
    <CheckboxCard
      className="w-full max-w-80"
      title="Enviar o recibo junto"
      description="O recibo sai por e-mail assim que o pagamento cair."
      defaultChecked
    />
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `title` | `ReactNode` | sim |  | - | O nome da opcao, em destaque: "Aviso por e-mail". |
| `checked` | `boolean` |  |  | - | Se a caixa está marcada agora. |
| `classNames` | `Partial<Record<"card" \| "control" \| "description" \| "icon" \| "title", string>>` |  |  | - | Classe por parte: `card` (o cartao inteiro, que e o `<label>`), `control` (a caixa), `icon`, `title` e `description`. |
| `defaultChecked` | `boolean` |  | `false` | - | Se a caixa começa marcada. |
| `description` | `ReactNode` |  |  | - | A letra miuda que ajuda a decidir: o que muda ao marcar. |
| `disabled` | `boolean` |  | `false` | - | Se a peça deve ignorar a interação do usuário. |
| `form` | `string` |  |  | - | Identifica o formulário dono do campo oculto. |
| `icon` | `ReactNode` |  |  | - | O desenho a esquerda do texto, escondido do leitor de tela. |
| `indeterminate` | `boolean` |  | `false` | - | Se a caixa está no estado misto: nem marcada, nem desmarcada. |
| `inputRef` | `Ref<HTMLInputElement>` |  |  | - | Uma ref para o `<input>` oculto. |
| `name` | `string` |  |  | - | Identifica o campo quando o formulário é enviado. |
| `nativeButton` | `boolean` |  | `false` | - | Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. |
| `onCheckedChange` | `((checked: boolean, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element \| undefined; }) => void)` |  |  | - | Chamado quando a caixa é marcada ou desmarcada. |
| `parent` | `boolean` |  | `false` | - | Se a caixa controla um grupo de caixas filhas. |
| `readOnly` | `boolean` |  | `false` | - | Se o usuário fica impedido de marcar ou desmarcar a caixa. |
| `render` | `ComponentRenderFn<HTMLProps, CheckboxRootState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | - | Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. |
| `required` | `boolean` |  | `false` | - | Se o usuário precisa marcar a caixa antes de enviar o formulário. |
| `uncheckedValue` | `string` |  |  | - | O valor enviado com o formulário quando a caixa está desmarcada. |
| `value` | `string` |  |  | - | O valor da caixa. |

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

## Ver também

- [AudioRecorder](/componentes/audio-recorder.md)
- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [ColorPicker](/componentes/color-picker.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
