Switch
Visão Geral
Design System
Para a documentação completa de design, incluindo diretrizes de uso, acessibilidade e exemplos visuais, consulte o Design System do GovBR.
Exemplo(s)
Propriedades
checked
| Atributo | checked |
|---|---|
| Descrição | Define o estado de seleção do checkbox. Se definido como verdadeiro, o checkbox estará marcado. Caso contrário, estará desmarcado. |
| Tipo | boolean |
| Valor padrão | false |
customId
| Atributo | custom-id |
|---|---|
| Descrição | Identificador único; gerado automaticamente quando omitido. |
| Tipo | string |
| Valor padrão | generateUniqueId() |
density
| Atributo | density |
|---|---|
| Descrição | Ajusta a área de interação: small é compacto, medium é o padrão e large é mais espaçado. |
| Tipo | "large" | "medium" | "small" |
| Valor padrão | 'medium' |
disabled
| Atributo | disabled |
|---|---|
| Descrição | Desativa o switch, tornando-o não interativo. |
| Tipo | boolean |
| Valor padrão | false |
hasIcon
| Atributo | has-icon |
|---|---|
| Depreciação | Use showIcon. |
| Descrição | Adiciona um ícone ao switch para indicar a mudança de estado. |
| Tipo | boolean |
| Valor padrão | false |
label
| Atributo | label |
|---|---|
| Descrição | Texto descritivo. Caso um slot seja utilizado para fornecer um texto alternativo, o valor desta propriedade será ignorado. |
| Tipo | string |
| Valor padrão | --- |
labelOff
| Atributo | label-off |
|---|---|
| Descrição | Texto exibido quando o switch está desativado. |
| Tipo | string |
| Valor padrão | --- |
labelOn
| Atributo | label-on |
|---|---|
| Descrição | Texto exibido quando o switch está ativado. |
| Tipo | string |
| Valor padrão | --- |
labelPosition
| Atributo | label-position |
|---|---|
| Descrição | Posição do rótulo em relação ao switch. |
| Tipo | "left" | "right" | "top" |
| Valor padrão | 'left' |
name
| Atributo | name |
|---|---|
| Descrição | Define o nome do switch, que é utilizado para agrupar switches em formulários e identificar o campo. O valor é obrigatório e deve ser fornecido para garantir o correto funcionamento em formulários. |
| Tipo | string |
| Valor padrão | --- |
required
| Atributo | required |
|---|---|
| Descrição | Se verdadeiro, o switch é obrigatório e deve ser ativado antes que o formulário possa ser enviado. |
| Tipo | boolean |
| Valor padrão | false |
showIcon
| Atributo | show-icon |
|---|---|
| Descrição | Exibe o ícone de estado. Quando informada, tem precedência sobre hasIcon. |
| Tipo | boolean |
| Valor padrão | --- |
validator
| Atributo | --- |
|---|---|
| Descrição | Regra síncrona ou assíncrona aplicada ao estado booleano do switch. |
| Tipo | (value: boolean) => string | Promise<string> |
| Valor padrão | --- |
value
| Atributo | value |
|---|---|
| Descrição | Define o valor associado ao switch quando ele faz parte de um formulário nativo (<form>).Esse valor é enviado com o formulário quando o switch está selecionado. Nota: Esta propriedade não deve ser utilizada para determinar se o switch está selecionado; para verificar o estado de seleção, use a propriedade checked. |
| Tipo | string |
| Valor padrão | --- |
Slots
| Nome | Descrição |
|---|---|
"default" | Slot para o rótulo do switch, com prioridade sobre a propriedade label. |
"feedback" | Mensagem de validação, normalmente um br-message. |
Eventos
| Evento | Descrição | Depreciação | Propagação |
|---|---|---|---|
brSwitchValidationChange | Emitido ao iniciar e concluir a validação customizada. | --- | true |
checkedChange | Disparado depois que o valor do checked foi alterado. | Use input/change e leia event.target.checked. | true |
Métodos
checkValidity
| Descrição | Retorna true se o valor do switch for válido, caso contrário false.Se o switch for inválido, dispara um evento 'invalid'. |
|---|---|
| Assinatura | checkValidity() => Promise<boolean> |
| Parâmetros | --- |
getValidationState
| Descrição | Retorna um snapshot serializável da Constraint Validation API. |
|---|---|
| Assinatura | getValidationState() => Promise<FormValidationState> |
| Parâmetros | --- |
reportValidity
| Descrição | Retorna true se o valor do componente for válido, caso contrário false.Se for inválido, exibe a mensagem de erro padrão do navegador. |
|---|---|
| Assinatura | reportValidity() => Promise<boolean> |
| Parâmetros | --- |
setCustomValidity
| Descrição | Define uma mensagem de validação customizada para o switch. Se a mensagem for uma string vazia, o erro customizado é limpo. |
|---|---|
| Assinatura | setCustomValidity(message: string) => Promise<void> |
| Parâmetros | message: |
toggleChecked
| Descrição | Inverte o valor da prop checked |
|---|---|
| Assinatura | toggleChecked() => Promise<void> |
| Depreciação | Atualize a propriedade checked diretamente. |
| Parâmetros | --- |
validate
| Descrição | Executa o validator do switch e retorna se o valor atual é válido. |
|---|---|
| Assinatura | validate() => Promise<boolean> |
| Parâmetros | --- |
Dependências
Usado por
Depende de
Gráfico
Migração de <br-switch> (1.x → 2.x)
O switch mantém o estado booleano e os dados de formulário. Os nomes dos rótulos e do posicionamento foram normalizados.
Propriedades e eventos
| API 1.x | API 2.x | Ação na migração |
|---|---|---|
checked, disabled, label, name, value | mesmos nomes | Mantenha. |
icon | showIcon | Use a propriedade canônica atual. |
labelChecked | labelOn | Renomeie. |
labelNotChecked | labelOff | Renomeie. |
onChange / update:checked | input / change | Atualize para os eventos nativos. |
size | density | Converta o tamanho para a densidade equivalente. |
top / right | labelPosition | Converta para a posição atual. |
Exemplo
1.x:
<br-switch label="Ativo" label-checked="Sim" label-not-checked="Não" size="large" top></br-switch>
2.x:
<br-switch label="Ativo" label-on="Sim" label-off="Não" density="large" label-position="top" show-icon></br-switch>
Validação
Para o contrato geral e a matriz de componentes, consulte o guia de formulários. Esta seção documenta o contrato específico do br-switch.
br-switch é um controle booleano associado a formulário. required exige checked=true; leia event.target.checked e use setCustomValidity() para regras adicionais.
Alterações externas, reset e restauração de estado não disparam eventos de usuário.
A mensagem é renderizada como br-message quando não existe feedback. Use o slot feedback para fornecer o conteúdo e manter a referência ARIA.
Para uma regra de domínio síncrona ou assíncrona, use validator. Ele recebe o estado booleano, pode ser acionado por await switchControl.validate() e emite brSwitchValidationChange.
Acessibilidade
Use label visível. O componente segue a semântica APG de switch, mantém aria-checked sincronizado e alterna com Espaço. O foco é delegado ao controle interno; não aplique role="checkbox" adicional no host.
Use texto para explicar o resultado da alternância e associe erros por aria-describedby.
Eventos nativos
Elemento HTML de referência
br-switch usa <input type="checkbox" role="switch"> e expõe o estado no host.
Como ouvir os eventos
const control = document.querySelector('br-switch');
control.addEventListener('change', () => console.log(control.checked));
Eventos nativos suportados
| Evento | Quando ocorre | Bubbles | Composed | Cancelable | Host | Observações |
|---|---|---|---|---|---|---|
change | estado alterna | Sim | Sim | Não | Sim | Uma ocorrência. |
click e foco | ativação/navegação | conforme o tipo | Sim | conforme o tipo | Sim | Preservados pelo controle interno. |
input | estado alterna | Sim | Sim | Não | Sim | Antes de change. |
Eventos não aplicáveis ou não suportados
Eventos de edição textual não se aplicam. Escrita em checked, reset e inicialização são silenciosos.
Eventos customizados
checkedChange é alias depreciado.
Valor, frameworks e acessibilidade
Leia event.target.checked; quando ligado, value participa de FormData. HTML e wrappers usam eventos padrão. Space alterna o switch e o nome acessível vem do label/slot.
Evidência de teste
src/shared/platform-contract.e2e.tsx cobre clique real, ordem, flags, target, caminho e FormData em Chromium headless.
