Radio Group

Agrupa `mk-radio` sob um rótulo comum e é dono do valor selecionado. Form-associated, com roving-tabindex e navegação por setas.

O mk-radio-group reúne opções mutuamente exclusivas sob uma única pergunta. O grupo é dono do valor selecionado: coordena a exclusividade entre os filhos, expõe o conjunto como um único ponto de parada do teclado e envia o valor no formulário. Funciona dentro ou fora de um <form>.

Quando usar

Duas ou mais opções mutuamente exclusivas precisam aparecer todas na tela ao mesmo tempo.
As opções pertencem à mesma pergunta e precisam de um rótulo comum.
O valor escolhido precisa participar do formulário com um único name.

Prefira alternativas quando:

As escolhas são independentes entre si — use mk-checkbox-group.
Cada item liga ou desliga um comportamento imediato — use mk-switch-group.
Há mais de cinco opções ou o espaço é reduzido — use mk-select.

Anatomia

#	Parte	Obrigatório?	Função
1	Rótulo do grupo	Sim	Enuncia a pergunta. Renderizado como `legend` do `fieldset` e usado como nome acessível.
2	Ícone de ajuda	Não	Tooltip com informação complementar sobre a pergunta, via `helperText`.
3	Asterisco	Não	Indica que a resposta é obrigatória, via `required`.
4	Opções	Sim	Os `mk-radio` slotados, dispostos em coluna ou lado a lado conforme `orientation`.

Padrão

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

<MkRadioGroup label="Plano de assinatura" name="plano" defaultValue="yearly">
  <MkRadio value="monthly" label="Mensal" />
  <MkRadio value="yearly" label="Anual" />
  <MkRadio value="lifetime" label="Vitalício" />
</MkRadioGroup>

<mk-radio-group label="Plano de assinatura" name="plano" default-value="yearly">
  <mk-radio value="monthly" label="Mensal"></mk-radio>
  <mk-radio value="yearly" label="Anual"></mk-radio>
  <mk-radio value="lifetime" label="Vitalício"></mk-radio>
</mk-radio-group>

Valor inicial e valor controlado

defaultValue marca a opção correspondente no primeiro render e depois sai do caminho. value mantém o valor sob controle do consumidor, que o atualiza ao receber mkChange. Use um ou outro, nunca os dois.

Quando nenhum dos dois é informado, o grupo adota o value do primeiro filho que já vier checked. Um defaultValue que não corresponde a nenhum filho deixa o grupo sem seleção inicial.

const [plano, setPlano] = useState('yearly');

<MkRadioGroup
  label="Plano de assinatura"
  value={plano}
  onMkChange={(e) => setPlano(e.detail.value)}
>
  <MkRadio value="monthly" label="Mensal" />
  <MkRadio value="yearly" label="Anual" />
</MkRadioGroup>

<mk-radio-group label="Plano de assinatura" [value]="plano" (mkChange)="plano = $event.detail.value">
  <mk-radio value="monthly" label="Mensal"></mk-radio>
  <mk-radio value="yearly" label="Anual"></mk-radio>
</mk-radio-group>

Obrigatório

required exibe o asterisco e marca o grupo como inválido enquanto nada estiver selecionado. Use requiredMessage para personalizar a mensagem de validação nativa.

<MkRadioGroup
  label="Forma de pagamento"
  name="pagamento"
  required
  requiredMessage="Escolha como quer pagar."
>
  <MkRadio value="card" label="Cartão" />
  <MkRadio value="pix" label="Pix" />
</MkRadioGroup>

<mk-radio-group
  label="Forma de pagamento"
  name="pagamento"
  required
  required-message="Escolha como quer pagar."
>
  <mk-radio value="card" label="Cartão"></mk-radio>
  <mk-radio value="pix" label="Pix"></mk-radio>
</mk-radio-group>

Orientação

orientation="horizontal" dispõe as opções lado a lado com quebra de linha. O padrão vertical mantém uma opção por linha.

<MkRadioGroup label="Tamanho" name="tamanho" orientation="horizontal" defaultValue="m">
  <MkRadio value="p" label="P" />
  <MkRadio value="m" label="M" />
  <MkRadio value="g" label="G" />
</MkRadioGroup>

<mk-radio-group label="Tamanho" name="tamanho" orientation="horizontal" default-value="m">
  <mk-radio value="p" label="P"></mk-radio>
  <mk-radio value="m" label="M"></mk-radio>
  <mk-radio value="g" label="G"></mk-radio>
</mk-radio-group>

Texto de ajuda

helperText renderiza o ícone de ajuda com tooltip ao lado do rótulo do grupo.

<MkRadioGroup
  label="Periodicidade"
  name="periodicidade"
  helperText="A cobrança acompanha a periodicidade escolhida."
>
  <MkRadio value="monthly" label="Mensal" />
  <MkRadio value="yearly" label="Anual" />
</MkRadioGroup>

<mk-radio-group
  label="Periodicidade"
  name="periodicidade"
  support-text="A cobrança acompanha a periodicidade escolhida."
>
  <mk-radio value="monthly" label="Mensal"></mk-radio>
  <mk-radio value="yearly" label="Anual"></mk-radio>
</mk-radio-group>

Desabilitado

disabled no grupo alcança todos os filhos. Ao reabilitar o grupo, cada filho volta ao disabled que ele próprio declarou. Uma opção individual também pode ser desabilitada — a navegação por setas pula essa opção.

<MkRadioGroup label="Plano" name="plano" disabled defaultValue="yearly">
  <MkRadio value="monthly" label="Mensal" />
  <MkRadio value="yearly" label="Anual" />
</MkRadioGroup>

<MkRadioGroup label="Plano" name="plano">
  <MkRadio value="monthly" label="Mensal" />
  <MkRadio value="yearly" label="Anual" disabled />
</MkRadioGroup>

<mk-radio-group label="Plano" name="plano" [disabled]="true" default-value="yearly">
  <mk-radio value="monthly" label="Mensal"></mk-radio>
  <mk-radio value="yearly" label="Anual"></mk-radio>
</mk-radio-group>

<mk-radio-group label="Plano" name="plano">
  <mk-radio value="monthly" label="Mensal"></mk-radio>
  <mk-radio value="yearly" label="Anual" [disabled]="true"></mk-radio>
</mk-radio-group>

Formulários

O grupo é form-associated: name é propagado para todos os filhos e o value selecionado é enviado na submissão. Em Angular, MkRadioGroupModule traz o ControlValueAccessor, então formControlName e ngModel funcionam direto no grupo.

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

import { MkRadioGroupModule, MkRadioModule } from '@db1/makuco-ui-angular';

@Component({
  imports: [ReactiveFormsModule, MkRadioGroupModule, MkRadioModule],
  // ...
})

<form [formGroup]="form" (ngSubmit)="submit()">
  <mk-radio-group label="Plano" formControlName="plano">
    <mk-radio value="monthly" label="Mensal"></mk-radio>
    <mk-radio value="yearly" label="Anual"></mk-radio>
  </mk-radio-group>
  <mk-button type="submit">Continuar</mk-button>
</form>

Props

Prop	Tipo	Padrão	Descrição
`label`	`string`	`""`	Texto do `legend`, usado como nome acessível do grupo.
`helperText`	`string`	—	Conteúdo do tooltip exibido ao passar o cursor sobre o ícone de ajuda.
`required`	`boolean`	`false`	Exibe o asterisco e marca o grupo como inválido enquanto nada estiver selecionado.
`requiredMessage`	`string`	i18n por `locale`	Mensagem do tooltip de validação nativa quando `required` e nada selecionado.
`locale`	`string`	—	Tag BCP 47 usada nas mensagens i18n. Herda `lang` do DOM quando omitido.
`disabled`	`boolean`	`false`	Desabilita o grupo inteiro, propagando o estado para todos os filhos.
`orientation`	`'horizontal' \\| 'vertical'`	`'vertical'`	Orientação das opções.
`name`	`string`	—	Atributo `name` propagado para os filhos e usado no envio do formulário.
`value`	`string`	—	Valor selecionado. Corresponde ao `value` de um dos filhos.
`defaultValue`	`string`	—	Valor inicial aplicado no primeiro render quando `value` não é informado.

Eventos

Evento	Componente	Payload	Descrição
`mkChange`	`mk-radio-group`	`{ value: string }`	Emitido quando a seleção muda por clique, teclado ou navegação por setas.

O mkChange de cada mk-radio filho é consumido pelo grupo e não sobe além dele, então o mkChange observado no grupo é sempre o do próprio grupo. Ouvintes ligados diretamente em um mk-radio continuam recebendo o evento dele.

Slots

Componente	Slot	Descrição
`mk-radio-group`	default	Instâncias de `mk-radio`, cada uma com seu próprio `value`.

Acessibilidade

O contêiner é um <fieldset role="radiogroup"> rotulado pelo <legend> via aria-labelledby.
aria-disabled="true" quando disabled; aria-required="true" quando required.
Roving-tabindex: o grupo inteiro é um único ponto de parada do Tab. O foco entra na opção selecionada, ou na primeira habilitada quando nada está selecionado.
Setas movem o foco e selecionam na mesma ação, conforme o padrão WAI-ARIA de radiogroup.
Cada mk-radio mantém seu role="radio" e o estado anunciado pelo leitor de tela.

Tecla	Comportamento
`Tab`	Entra ou sai do grupo inteiro
`↓` `→`	Move para a próxima opção habilitada e a seleciona
`↑` `←`	Move para a opção habilitada anterior e a seleciona
`Home`	Seleciona a primeira opção habilitada
`End`	Seleciona a última opção habilitada
`Space`	Seleciona a opção focada

Rótulo do grupo: o label enuncia a pergunta e é lido antes de cada opção. Sem ele, o leitor de tela anuncia apenas os rótulos individuais, fora de contexto.

Uso de cor: o asterisco de obrigatório é um sinal visual — acompanhe com mensagem de validação ao submeter.

Radio Group

On this page