Radio

O mk-radio representa uma opção dentro de um grupo de seleção mutuamente exclusiva. Componentes com o mesmo atributo name formam um grupo — o navegador garante que apenas um pode estar selecionado por vez.

Quando usar

Use mk-radio quando:

• O usuário precisa escolher uma única opção de uma lista de 2 a 5 alternativas visíveis simultaneamente.
• As opções são mutuamente exclusivas e o usuário precisa ver todas antes de decidir (ex.: planos de assinatura, métodos de pagamento, nível de permissão).
• É importante expor as opções na tela sem precisar abrir um menu.

Prefira alternativas quando:

• Há mais de 5 opções — use mk-select para não poluir o layout.
• A seleção é independente entre itens — use mk-checkbox.
• Há apenas uma opção binária ligado/desligado — use mk-switch.
• O espaço é muito reduzido — use mk-select.

Anatomia

Variantes

• Default (não selecionado): controle circular vazio, borda neutra. Disponível mas ainda não escolhido.
• Checked (selecionado): ponto preenchido dentro do círculo; borda muda para a cor da marca.
• Error: borda do controle e rótulo em cor de erro semântico. Sempre acompanhe com texto auxiliar orientando a ação.

Comportamento

Funciona sempre em grupo — nunca isolado. Ao clicar em uma opção, ela é marcada e qualquer outra selecionada no grupo é desmarcada automaticamente.

O rótulo é clicável: clicar sobre o texto tem o mesmo efeito que clicar no controle, ampliando a área de toque.

Em formulários, o estado de erro é ativado na tentativa de envio sem seleção. Ao selecionar qualquer opção do grupo, o erro é removido imediatamente.

Estados

Composição

Radio Buttons sempre em grupo de 2 ou mais opções relacionadas, sob um rótulo comum descrevendo a pergunta ou categoria. Espaçamento consistente entre opções.

Quando opções crescem ou espaço é limitado, prefira mk-select. Para seleções independentes, use mk-checkbox. Para binário ligado/desligado, use mk-switch.

Padrão

import { MkRadio } from '@db1/makuco-ui-react';

<MkRadio label="Opção A" name="grupo" value="a" />
<MkRadio label="Opção B" name="grupo" value="b" checked />
<MkRadio label="Opção C" name="grupo" value="c" />

<mk-radio label="Opção A" name="grupo" value="a"></mk-radio>
<mk-radio label="Opção B" name="grupo" value="b" checked></mk-radio>
<mk-radio label="Opção C" name="grupo" value="c"></mk-radio>

Erro

Use error para indicar que a seleção é inválida. O estado de erro é suprimido quando o componente está desabilitado.

<MkRadio label="Opção inválida" error />

<mk-radio label="Opção inválida" error></mk-radio>

Obrigatório

Quando required, o formulário não pode ser submetido sem que o radio esteja selecionado. Use requiredMessage para personalizar a mensagem de validação nativa do navegador.

<MkRadio label="Aceito os termos" required requiredMessage="Selecione uma opção para continuar." />

<mk-radio label="Aceito os termos" required required-message="Selecione uma opção para continuar."></mk-radio>

Desabilitado

<MkRadio label="Não selecionado" disabled />
<MkRadio label="Selecionado" disabled checked />

<mk-radio label="Não selecionado" [disabled]="true"></mk-radio>
<mk-radio label="Selecionado" [disabled]="true" checked></mk-radio>

Texto de ajuda

Use supportText para exibir um tooltip explicativo ao passar o cursor sobre o ícone de interrogação.

<MkRadio
  label="Opção avançada"
  supportText="Esta opção habilita o modo avançado de configuração."
/>

<mk-radio
  label="Opção avançada"
  helper-text="Esta opção habilita o modo avançado de configuração."
></mk-radio>

Formulários

O mk-radio é form-associated: o value do radio selecionado é enviado com o name do grupo ao submeter o formulário.

<form onSubmit={handleSubmit}>
  <MkRadio label="Mensal" name="plano" value="monthly" />
  <MkRadio label="Anual" name="plano" value="yearly" checked />
  <MkButton type="submit">Continuar</MkButton>
</form>

<form (ngSubmit)="handleSubmit()">
  <mk-radio label="Mensal" name="plano" value="monthly"></mk-radio>
  <mk-radio label="Anual" name="plano" value="yearly" checked></mk-radio>
  <mk-button type="submit">Continuar</mk-button>
</form>

Props

Eventos

Acessibilidade

• Usa <input type="radio"> nativo — navegação por teclado (Tab para focar, Setas para navegar dentro do grupo, Space para selecionar) inclusa.
• aria-invalid="true" aplicado automaticamente quando error e não disabled.
• aria-required="true" aplicado quando required.
• Label associado via htmlFor — leitores de tela anunciam o nome acessível corretamente.
• Form-associated via ElementInternals: o name/value participam da submissão nativa de formulários.
• O navegador gerencia a exclusividade mútua nativamente para radios com o mesmo name.

Rótulos e identificação: cada opção deve ter rótulo visível e descritivo. O grupo inteiro precisa de um título explicando o que está sendo perguntado. No handoff para o dev, sinalize que o grupo deve usar fieldset e legend (ou equivalente ARIA) para que leitores de tela anunciem a pergunta antes de cada opção.

Navegação por teclado: dentro de um grupo, navegação com teclas de seta — não com Tab. O Tab deve pular o grupo inteiro, parando apenas na opção selecionada ou na primeira se nenhuma estiver marcada.

Indicador de foco: outline ao redor do controle circular deve ser claramente visível. Não confundir com hover.

Uso de cor: o estado Erro muda a borda e o rótulo para vermelho — mas cor sozinha não é suficiente. Sempre acompanhe com texto auxiliar como "Selecione uma das opções para continuar".

Estado desabilitado: redução de contraste é intencional. Se desabilitado por razão específica, comunique por outro meio (tooltip, nota no formulário).