Switch

O mk-switch representa um controle de alternância binária — ligado ou desligado. É semanticamente diferente de um checkbox: use-o quando a ação tem efeito imediato (ex.: ativar notificações) em vez de acumular seleções para submissão posterior.

Quando usar

Use o mk-switch quando:

• A ação é imediata — ligar notificações, ativar modo escuro, habilitar permissão.
• O resultado é binário: ligado ou desligado.
• O usuário não precisa confirmar antes da mudança ter efeito.

Prefira outra alternativa quando:

• A mudança só terá efeito após envio de formulário — use mk-checkbox.
• Há mais de duas opções — use mk-radio ou mk-select.
• A ação é destrutiva ou irreversível — prefira botão com confirmação explícita, pois o switch não tem passo de confirmação.

Anatomia

Variantes

• Posição do rótulo à direita (padrão): rótulo à direita do controle. Padrão para listas de configurações.
• Posição do rótulo à esquerda: rótulo à esquerda do controle. Para formulários com labels à esquerda ou tabelas de permissões.

Comportamento

O Switch muda de estado imediatamente ao clicar — sem etapa de confirmação. Ao ativar, a trilha muda para verde (success-900) e o thumb desliza para a direita. Ao desativar, a trilha volta ao neutro.

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

O rótulo deve descrever o que está sendo controlado, não o estado atual. Evite "Ativado" ou "Desligado" — prefira "Receber notificações" ou "Modo escuro".

Estados

Composição

O mk-switch aparece com mais frequência em páginas de configurações, painéis de preferências e listas de permissões — sempre um item por linha, com rótulo claro. Quando vários switches aparecem agrupados, mantenha alinhamento e espaçamento consistentes.

Para seleções que terão efeito após envio de formulário, use mk-checkbox. Para escolhas entre mais de duas opções, use mk-radio.

Padrão

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

<MkSwitch label="Notificações" />
<MkSwitch label="Notificações" checked />

<mk-switch label="Notificações"></mk-switch>
<mk-switch label="Notificações" checked></mk-switch>

Posição do rótulo

Use labelPosition="start" para posicionar o rótulo antes do toggle.

<MkSwitch label="Rótulo no início" labelPosition="start" />
<MkSwitch label="Rótulo no fim" labelPosition="end" />

<mk-switch label="Rótulo no início" label-position="start"></mk-switch>
<mk-switch label="Rótulo no fim" label-position="end"></mk-switch>

Obrigatório

Quando required, o formulário não pode ser submetido sem que o switch esteja ligado.

<MkSwitch label="Aceito os termos de uso" required />

<mk-switch label="Aceito os termos de uso" required></mk-switch>

Desabilitado

<MkSwitch label="Desligado" disabled />
<MkSwitch label="Ligado" disabled checked />

<mk-switch label="Desligado" [disabled]="true"></mk-switch>
<mk-switch label="Ligado" [disabled]="true" checked></mk-switch>

Formulários

O mk-switch é form-associated: quando ligado, envia o value com o name ao submeter o formulário. Quando desligado, nenhum valor é enviado.

<form onSubmit={handleSubmit}>
  <MkSwitch label="Receber e-mails de marketing" name="marketing" value="yes" />
  <MkButton type="submit">Salvar preferências</MkButton>
</form>

<form (ngSubmit)="handleSubmit()">
  <mk-switch label="Receber e-mails de marketing" name="marketing" value="yes"></mk-switch>
  <mk-button type="submit">Salvar preferências</mk-button>
</form>

Props

Eventos

Acessibilidade

• Usa <input type="checkbox" role="switch"> — suporte a teclado (Tab para focar, Space para alternar) incluso.
• aria-checked="true" ou "false" reflete o estado do switch para leitores de tela.
• 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.
• role="switch" garante que leitores de tela anunciem o componente como um controle de alternância, e não como um checkbox.

Rótulos e identificação: o rótulo deve descrever a funcionalidade controlada, não o estado atual. "Notificações por e-mail" é um bom rótulo — "Ativado" não é. O elemento possui role="switch" e o estado (aria-checked) é anunciado automaticamente ao mudar.

Indicador de foco: outline ao redor do controle inteiro (trilha + thumb). Nunca remover o foco visual. O switch deve ser acionado com Space quando focado.

Estado desabilitado: quando desabilitado por razão específica (ex.: requer permissão de conta), comunique o motivo por outro meio — tooltip ou nota abaixo do componente.