Switch

Componente estável e recomendada para novos projetos.

Anatomia, uso, comportamento visual e recomendações conceituais são mantidos pelo Padrão Digital de Governo. Esta página documenta a implementação Web Components e sua API executável.

Visão Geral

O componente br-switch é o interruptor de alternância do GovBR-DS, desenvolvido para ativar ou desativar instantaneamente um recurso, modo ou configuração na interface.

Para que serve

• Alternância binária imediata: Alterna entre dois estados mutuamente exclusivos (ligado/desligado, ativo/inativo, habilitado/desabilitado) com efeito imediato na aplicação.
• Rótulo contextual dinâmico: Suporta textos explicativos de estado (ex.: "Ativado" / "Desativado") e ícones de apoio.
• Acessibilidade nativa WAI-ARIA: Utiliza internamente o papel semântico role="switch" com o atributo aria-checked, garantindo anúncio claro de estado para leitores de tela.

Quando utilizar

• Utilize quando:
  • A alteração de estado entrar em vigor imediatamente após a interação, sem depender de um botão "Salvar" ou submissão de formulário.
  • Para preferências do sistema (ex.: "Tema escuro", "Notificações ativas", "Wi-Fi ligado").
• Evite e prefira outro componente quando:
  • A escolha fizer parte de um formulário com múltiplos campos que serão submetidos juntos (prefira br-checkbox).
  • A escolha for entre duas opções com nomes explícitos diferentes de ligado/desligado (prefira br-radio).

Estrutura e Slots

O br-switch é um controle direto:

• default: Slot para personalização do rótulo descritivo do switch (com prioridade sobre a propriedade label).
• feedback: Slot para mensagens de validação contextual (como br-message).

Para a documentação completa de design, incluindo diretrizes de acessibilidade e especificações visuais, consulte o Design System do GovBR.

Exemplo(s)

Desktop (100%)

Tablet - 768px

iPhone (iOS) - 390x844

Android - 360x800

Padrão

Compartilhar URL

Ativar movimento reduzido

Mudar fundo

Abrir no StackBlitz

Mais opções

Tela cheia

Carregando preview…

HTML

Controles do componente

Console: logs, eventos e erros

Angular (Somente leitura)

React (Somente leitura)

Vue (Somente leitura)

Acessibilidade

Recolher controles e código

Desfazer alteração

Refazer alteração

Comparar alterações

Formatar código

Resetar código para o estado inicial

Escolher formato para copiar

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. Valores inválidos usam medium.
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 Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

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. Valores inválidos usam left.
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 Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Atributo	---
Descrição	Regra síncrona ou assíncrona aplicada ao estado booleano do switch. Retorne uma mensagem para invalidar ou null para aceitar o valor.
Exemplo de uso	const toggle = document.querySelector('br-switch'); toggle.validator = (checked) => checked ? null : 'Ative esta opção para continuar';
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 Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.	Emitido ao iniciar e concluir a validação customizada.	---	true
checkedChange Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.	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 Componente mantido por compatibilidade; prefira a alternativa indicada na documentação.

Descrição	Inverte o valor da prop checked
Assinatura	toggleChecked() => Promise<void>
Depreciação	Atualize a propriedade checked diretamente.
Parâmetros	---

validate Componente/funcionalidade ainda em testes. Use com cuidado, pois podemos fazer alterações.

Descrição	Executa o validator do switch e retorna se o valor atual é válido.
Assinatura	validate() => Promise<boolean>
Parâmetros	---

CSS Shadow Parts

Nome	Descrição
"container"	Contêiner visual do switch.
"data"	Elemento com textos de estado ligado/desligado.
"feedback"	Contêiner da mensagem de validação.
"input"	Elemento input nativo com role switch.
"label"	Rótulo do 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/contracts/platform-contract.e2e.tsx cobre clique real, ordem, flags, target, caminho e FormData em Chromium headless.

Atributos nativos

O host FACE usa name, value, checked, required, disabled, form e autofocus. O controle interno mantém semântica de switch e sincroniza o valor submetido.

indeterminate não é aplicável ao contrato binário do switch. form e autofocus são fornecidos pela plataforma, sem props dedicadas.

Dependências

Usado por

• br-cookiebar-cookie

Depende de

• br-message

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>