# RadioCard

Opção em cartão, dentro de um `RadioGroup`: forma de pagamento, plano, frete.

Cada cartão é um `Radio` inteiro, com `title` em destaque, `description` na
letra miúda e `icon` à esquerda. O cartão todo é o alvo: clicar no texto, no
ícone ou na borda escolhe. O `title` é o nome que o leitor de tela anuncia, e
a `description` vira a descrição do radio (`aria-describedby`), então quem
ouve a tela escuta "Boleto, compensa em até 3 dias úteis". O escolhido troca a
borda para o acento, e o círculo continua lá, porque cor sozinha não diz o
estado.

```tsx
<RadioGroup aria-label="Forma de pagamento" defaultValue="pix">
  <RadioCard value="pix" title="Pix" description="Cai na hora." />
  <RadioCard value="boleto" title="Boleto" description="Compensa em até 3 dias úteis." />
</RadioGroup>
```

O `RadioGroup` empilha os cartões; para pô-los lado a lado, troque o
`className` dele por uma grade (`grid grid-cols-1 gap-2 sm:grid-cols-2`). O
`className` do `RadioCard` veste o cartão, e `classNames` alcança `card`,
`control`, `icon`, `title` e `description`. `disabled` desliga a opção, que
fica no lugar com a cara de desligada.

## Quando não usar

Quando as opções são curtas e não precisam de explicação (sim ou não, um
status), use `Radio` no `RadioGroup`: cartão ocupa quatro vezes a altura e
empurra o resto do formulário para baixo. Quando mais de uma vale, é
`CheckboxCard`. E com mais de seis opções, cartão vira rolagem: é `Select`.

## No React Native

Traduz pelo nome e pelas partes do web: `title`, `description`, `icon`, `disabled`, `invalid` e `classNames` (`card`, `control`, `icon`, `title`, `description`). O cartão inteiro é o alvo do toque, com papel `radio` e o estado `checked`, e a escolhida troca a borda para o acento.

**Controlado por `checked` e `onCheckedChange`.** No web o `RadioCard` mora dentro de um `RadioGroup` que guarda o valor; no nativo o `RadioGroup` recebe `items` e não tem filhos, então cada cartão diz se está escolhido, e o toque no que ainda não está chama `onCheckedChange(true)`. Ponha os cartões numa `View` com `accessibilityRole="radiogroup"` e o nome da pergunta.

**`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 `RadioGroup variant="card"`, decisão escrita como `vira`. Um app real precisou escolher pelo desenho - o tema, o plano com a ilustração -, e o `icon` do `ToggleGroup` e o do cartão cabem em 16 a 20pt, que não serve para isso. `media` ocupa a largura do cartão, em cima do texto, no tamanho que quem a passa escolher, e fica escondida do leitor de tela, que ouve o `title`. O `RadioGroup variant="card"` continua sendo o atalho para a lista sem desenho grande.

## Importação

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

## Exemplos

### Forma de pagamento

```tsx
import { RadioCard, RadioGroup } from '@rivocode/ui'
import { Barcode, CreditCard, QrCode } from 'lucide-react'

export function PaymentMethod() {
  return (
    <RadioGroup aria-label="Forma de pagamento" defaultValue="pix" className="w-80">
      <RadioCard
        value="pix"
        title="Pix"
        description="Cai na hora, inclusive no fim de semana."
        icon={<QrCode size={18} />}
      />
      <RadioCard
        value="boleto"
        title="Boleto"
        description="Compensa em até 3 dias úteis."
        icon={<Barcode size={18} />}
      />
      <RadioCard
        value="cartao"
        title="Cartão de crédito"
        description="Em até 12 vezes, com juros da operadora."
        icon={<CreditCard size={18} />}
        disabled
      />
    </RadioGroup>
  )
}
```

### Plano, sem ícone

```tsx
import { RadioCard, RadioGroup } from '@rivocode/ui'
import { Barcode, CreditCard, QrCode } from 'lucide-react'

export function Plan() {
  return (
    <RadioGroup aria-label="Plano" defaultValue="anual" className="grid w-full max-w-lg grid-cols-1 gap-2 sm:grid-cols-2">
      <RadioCard value="mensal" title="Mensal" description="R$ 89 por mês" />
      <RadioCard value="anual" title="Anual" description="R$ 890 por ano, dois meses grátis" />
    </RadioGroup>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Padrão | Desde | O que faz |
| --- | --- | --- | --- | --- | --- |
| `title` | `ReactNode` | sim |  | - | O nome da opcao, em destaque: "Pix". |
| `value` | `unknown` | sim |  | - | O valor único que identifica a opção no grupo. |
| `classNames` | `Partial<Record<"card" \| "control" \| "description" \| "icon" \| "title", string>>` |  |  | - | Classe por parte: `card` (o cartao inteiro, que e o `<label>`), `control` (o circulo), `icon`, `title` e `description`. |
| `description` | `ReactNode` |  |  | - | A letra miuda que ajuda a decidir: prazo, custo, condicao. |
| `disabled` | `boolean` |  |  | - | Se a peça deve ignorar a interação do usuário. |
| `icon` | `ReactNode` |  |  | - | O desenho a esquerda do texto, escondido do leitor de tela. |
| `inputRef` | `Ref<HTMLInputElement>` |  |  | - | Uma ref para acessar o campo oculto. |
| `nativeButton` | `boolean` |  | `false` | - | Se a peça renderiza um `<button>` nativo quando é trocada pela prop `render`. |
| `readOnly` | `boolean` |  |  | - | Se o usuário fica impedido de escolher a opção. |
| `render` | `ComponentRenderFn<HTMLProps, RadioRootState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  |  | - | Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente. |
| `required` | `boolean` |  |  | - | Se o usuário precisa escolher um valor antes de enviar o formulário. |

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)
- [CheckboxCard](/componentes/checkbox-card.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)
