Switch Group

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

O mk-switch-group reúne alternâncias relacionadas sob um único rótulo — canais de notificação, preferências de privacidade, recursos opcionais. Cada mk-switch filho continua dono do próprio checked; o grupo aplica o valor inicial, propaga disabled e emite um mkChange agregado.

Quando usar

Várias preferências liga/desliga pertencem ao mesmo assunto.
Cada alternância tem efeito imediato, sem depender de submissão.
O leitor de tela precisa anunciar o assunto antes de cada alternância.

Prefira alternativas quando:

As escolhas só valem após submeter um formulário — use mk-checkbox-group.
Apenas uma opção pode ser escolhida — use mk-radio-group.

Anatomia

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

Padrão

import { MkSwitch, MkSwitchGroup } from '@db1/makuco-ui-react';

<MkSwitchGroup label="Notificações" defaultValue={['email']}>
  <MkSwitch value="email" label="E-mail" />
  <MkSwitch value="sms" label="SMS" />
  <MkSwitch value="push" label="Push" />
</MkSwitchGroup>

<mk-switch-group label="Notificações" [defaultValue]="['email']">
  <mk-switch value="email" label="E-mail"></mk-switch>
  <mk-switch value="sms" label="SMS"></mk-switch>
  <mk-switch value="push" label="Push"></mk-switch>
</mk-switch-group>

Valor inicial

defaultValue recebe a lista de valores ligados no primeiro render. A propagação acontece uma vez por filho: depois disso cada mk-switch segue independente. 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 [canais, setCanais] = useState(['email']);

<MkSwitchGroup
  label="Notificações"
  defaultValue={['email']}
  onMkChange={(e) => setCanais(e.detail.values)}
>
  <MkSwitch value="email" label="E-mail" />
  <MkSwitch value="sms" label="SMS" />
</MkSwitchGroup>

<mk-switch-group
  label="Notificações"
  [defaultValue]="['email']"
  (mkChange)="canais = $event.detail.values"
>
  <mk-switch value="email" label="E-mail"></mk-switch>
  <mk-switch value="sms" label="SMS"></mk-switch>
</mk-switch-group>

Obrigatório

required exibe o asterisco e define aria-required no grupo. A validação continua sendo de cada mk-switch filho.

<MkSwitchGroup label="Consentimentos" required>
  <MkSwitch value="tracking" label="Permitir análise de uso" />
  <MkSwitch value="marketing" label="Receber ofertas" />
</MkSwitchGroup>

<mk-switch-group label="Consentimentos" required>
  <mk-switch value="tracking" label="Permitir análise de uso"></mk-switch>
  <mk-switch value="marketing" label="Receber ofertas"></mk-switch>
</mk-switch-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.

<MkSwitchGroup label="Recursos" orientation="horizontal">
  <MkSwitch value="beta" label="Beta" />
  <MkSwitch value="dark" label="Tema escuro" />
  <MkSwitch value="sound" label="Som" />
</MkSwitchGroup>

<mk-switch-group label="Recursos" orientation="horizontal">
  <mk-switch value="beta" label="Beta"></mk-switch>
  <mk-switch value="dark" label="Tema escuro"></mk-switch>
  <mk-switch value="sound" label="Som"></mk-switch>
</mk-switch-group>

Texto de ajuda

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

<MkSwitchGroup
  label="Notificações"
  helperText="Os avisos críticos são sempre enviados por e-mail."
>
  <MkSwitch value="email" label="E-mail" />
  <MkSwitch value="sms" label="SMS" />
</MkSwitchGroup>

<mk-switch-group
  label="Notificações"
  support-text="Os avisos críticos são sempre enviados por e-mail."
>
  <mk-switch value="email" label="E-mail"></mk-switch>
  <mk-switch value="sms" label="SMS"></mk-switch>
</mk-switch-group>

Desabilitado

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

<MkSwitchGroup label="Notificações" disabled defaultValue={['email']}>
  <MkSwitch value="email" label="E-mail" />
  <MkSwitch value="sms" label="SMS" />
</MkSwitchGroup>

<mk-switch-group label="Notificações" [disabled]="true" [defaultValue]="['email']">
  <mk-switch value="email" label="E-mail"></mk-switch>
  <mk-switch value="sms" label="SMS"></mk-switch>
</mk-switch-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 ligados no primeiro render. Aplicado uma vez por filho.

Eventos

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

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

Slots

Componente	Slot	Descrição
`mk-switch-group`	default	Instâncias de `mk-switch`, 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-switch avulso.
Cada mk-switch mantém role="switch" e aria-checked próprios.

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

Rótulo do grupo: o label nomeia o assunto e é lido antes de cada alternância. Sem ele, o leitor de tela anuncia apenas os rótulos individuais, fora de contexto.

Switch Group

On this page