Checkbox Group

Agrupa `mk-checkbox` sob um rótulo comum, com layout e semântica de grupo. Cada filho continua independente.

O mk-checkbox-group reúne escolhas independentes sob uma única pergunta. Cada mk-checkbox filho continua dono do próprio checked e da própria participação no formulário; o grupo aplica o valor inicial, propaga disabled e emite um mkChange agregado.

Quando usar

Várias opções relacionadas podem ser marcadas ao mesmo tempo.
As opções pertencem à mesma pergunta e precisam de um rótulo comum.
O leitor de tela precisa anunciar a pergunta antes de cada opção.

Prefira alternativas quando:

Apenas uma opção pode ser escolhida — use mk-radio-group.
Cada item liga ou desliga um comportamento imediato — use mk-switch-group.
Há muitas opções e o espaço é reduzido — use mk-select em modo múltiplo.

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-checkbox` slotados, dispostos em coluna ou lado a lado conforme `orientation`.

Padrão

import { MkCheckbox, MkCheckboxGroup } from '@db1/makuco-ui-react';

<MkCheckboxGroup label="Áreas de interesse" defaultValue={['design']}>
  <MkCheckbox value="design" label="Design" />
  <MkCheckbox value="code" label="Desenvolvimento" />
  <MkCheckbox value="ops" label="Infraestrutura" />
</MkCheckboxGroup>

<mk-checkbox-group label="Áreas de interesse" [defaultValue]="['design']">
  <mk-checkbox value="design" label="Design"></mk-checkbox>
  <mk-checkbox value="code" label="Desenvolvimento"></mk-checkbox>
  <mk-checkbox value="ops" label="Infraestrutura"></mk-checkbox>
</mk-checkbox-group>

Valor inicial

defaultValue recebe a lista de valores marcados no primeiro render. A propagação acontece uma vez por filho: depois disso cada mk-checkbox segue independente, e marcar um não altera os demais. Filhos adicionados após o mount recebem o defaultValue na primeira vez que o grupo os enxerga.

O estado agregado vive no app — acompanhe-o pelo mkChange do grupo.

const [areas, setAreas] = useState(['design']);

<MkCheckboxGroup
  label="Áreas de interesse"
  defaultValue={['design']}
  onMkChange={(e) => setAreas(e.detail.values)}
>
  <MkCheckbox value="design" label="Design" />
  <MkCheckbox value="code" label="Desenvolvimento" />
</MkCheckboxGroup>

<mk-checkbox-group
  label="Áreas de interesse"
  [defaultValue]="['design']"
  (mkChange)="areas = $event.detail.values"
>
  <mk-checkbox value="design" label="Design"></mk-checkbox>
  <mk-checkbox value="code" label="Desenvolvimento"></mk-checkbox>
</mk-checkbox-group>

Obrigatório

required exibe o asterisco e define aria-required no grupo. A validação continua sendo de cada mk-checkbox filho — o grupo não agrega regras como "selecione ao menos um".

<MkCheckboxGroup label="Termos" required>
  <MkCheckbox value="terms" label="Aceito os termos de uso" required />
  <MkCheckbox value="news" label="Quero receber novidades" />
</MkCheckboxGroup>

<mk-checkbox-group label="Termos" required>
  <mk-checkbox value="terms" label="Aceito os termos de uso" required></mk-checkbox>
  <mk-checkbox value="news" label="Quero receber novidades"></mk-checkbox>
</mk-checkbox-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.

<MkCheckboxGroup label="Dias de entrega" orientation="horizontal">
  <MkCheckbox value="mon" label="Seg" />
  <MkCheckbox value="tue" label="Ter" />
  <MkCheckbox value="wed" label="Qua" />
</MkCheckboxGroup>

<mk-checkbox-group label="Dias de entrega" orientation="horizontal">
  <mk-checkbox value="mon" label="Seg"></mk-checkbox>
  <mk-checkbox value="tue" label="Ter"></mk-checkbox>
  <mk-checkbox value="wed" label="Qua"></mk-checkbox>
</mk-checkbox-group>

Texto de ajuda

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

<MkCheckboxGroup label="Áreas de interesse" helperText="Selecione quantas áreas quiser.">
  <MkCheckbox value="design" label="Design" />
  <MkCheckbox value="code" label="Desenvolvimento" />
</MkCheckboxGroup>

<mk-checkbox-group label="Áreas de interesse" support-text="Selecione quantas áreas quiser.">
  <mk-checkbox value="design" label="Design"></mk-checkbox>
  <mk-checkbox value="code" label="Desenvolvimento"></mk-checkbox>
</mk-checkbox-group>

Desabilitado

disabled no grupo alcança todos os filhos. Ao reabilitar o grupo, cada filho volta ao disabled que ele próprio declarou.

<MkCheckboxGroup label="Áreas de interesse" disabled defaultValue={['design']}>
  <MkCheckbox value="design" label="Design" />
  <MkCheckbox value="code" label="Desenvolvimento" />
</MkCheckboxGroup>

<mk-checkbox-group label="Áreas de interesse" [disabled]="true" [defaultValue]="['design']">
  <mk-checkbox value="design" label="Design"></mk-checkbox>
  <mk-checkbox value="code" label="Desenvolvimento"></mk-checkbox>
</mk-checkbox-group>

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 define `aria-required`. A validação continua em cada filho.
`disabled`	`boolean`	`false`	Desabilita o grupo inteiro, propagando o estado para todos os filhos.
`orientation`	`'horizontal' \\| 'vertical'`	`'vertical'`	Orientação das opções.
`defaultValue`	`string[]`	—	Valores marcados no primeiro render. Aplicado uma vez por filho.

Eventos

Evento	Componente	Payload	Descrição
`mkChange`	`mk-checkbox-group`	`{ values: string[] }`	Emitido quando qualquer filho muda, com os valores marcados no momento do disparo.

O mkChange de cada mk-checkbox 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-checkbox continuam recebendo o evento dele.

Slots

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

Acessibilidade

O contêiner é um <fieldset role="group"> rotulado pelo <legend> via aria-labelledby.
aria-disabled="true" quando disabled; aria-required="true" quando required.
Cada filho mantém seu próprio ponto de parada do Tab, como qualquer mk-checkbox avulso.
Setas não navegam entre checkboxes — é o comportamento esperado para grupos de checkbox no padrão WAI-ARIA.

Tecla	Comportamento
`Tab`	Move para a próxima opção do grupo
`Space` `Enter`	Alterna a opção focada, tratado pelo próprio `mk-checkbox`

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.

Checkbox Group

On this page