Alternar entre dois estados opostos: uma opção que admite apenas dois valores contrários e reversíveis (on/off, visível/oculto, sim/não), sem posições intermediárias. Ex.: "Modo férias", "Mostrar o preço no catálogo".
Habilitar uma funcionalidade: controlar de forma independente cada item de um conjunto de opções. Ex.: ativar um meio de envio ou um canal de notificação.
Mostrar ou ocultar um elemento: expor ou esconder algo de imediato na loja ou no painel. Ex.: "Mostrar o produto na loja", "Mostrar no checkout".

Quando não usar

Registrar uma opção com salvamento: uma opção que só é aplicada ao confirmar o formulário com um botão (quando a mudança não é imediata). Em vez disso, usar Checkbox.
Escolher uma opção excludente: selecionar uma única opção entre várias mutuamente exclusivas. Em vez disso, usar Radio.
Executar uma ação pontual: disparar algo em vez de manter um estado on/off persistente. Em vez disso, usar Button. Ex.: "Salvar", "Publicar".

Anatomia

Label

Track: controle em formato de pílula que representa a posição on/off e recebe a interação.
Thumb: círculo que se desloca dentro do track para sinalizar a posição ativa ou inativa.
Label: texto opcional que descreve a configuração que o track controla.

Estados

Aplicação

Costuma aparecer em painéis de configuração, cabeçalhos de cartões e linhas de uma lista, alinhado à direita de um título que descreve a opção e, quando necessário, uma descrição de apoio.

Receber notificações por e-mail

Receber notificações por WhatsApp

Do and Don'ts

Mostrar no checkout

Usar Toggle quando a mudança se aplica de imediato, sem uma etapa de salvamento.

Mostrar no checkout

Evitar Toggle quando a opção só é aplicada ao confirmar o formulário com um botão; nesse caso usar Checkbox.

Mostrar o preço no catálogo

Redigir a etiqueta no positivo, descrevendo o que é ativado ao ligar o seletor.

Não ocultar o preço no catálogo

Evitar etiquetas no negativo: ao ativá-las geram uma dupla negação difícil de interpretar.

Mostrar o estoque na loja

Permitir compras sem estoque

Usar um Toggle para cada configuração binária independente.

Faturamento mensal

Faturamento anual

Evitar vários Toggle para opções mutuamente exclusivas; nesse caso usar Radio.

Acessibilidade

Etiqueta acessível: acompanhar o controle com um label visível ou, se o texto ficar fora do componente, com um aria-label que descreva a configuração, para que os leitores de tela anunciem o que é ativado ou desativado.
Navegação por teclado: o controle é alcançado com Tab e ativado com a barra de espaço, já que renderiza um <input type="checkbox"> nativo.
Foco visível: o Nimbus aplica um anel de foco próprio com :focus-visible ao navegar por teclado; não suprimir o outline ao personalizar estilos.
Estado desabilitado: usar a prop disabled, não simulá-lo com cor ou opacidade; o input desabilitado comunica o estado inativo às tecnologias assistivas.

Guia de conteúdo

O Toggle nomeia a configuração que é ativada ou desativada. A pessoa deve entender o que ele controla só de ler o label, sem precisar ativá-lo para descobrir.

Regras de conteúdo

Capitalização: sentence case. Só nomes próprios levam maiúscula.
Comprimento: 1 a 3 palavras idealmente, no máximo 5 se o contexto exigir.
Pontuação: sem ponto final.
Forma verbal: frase nominal quando o nome da configuração é claro por si só ("Frete grátis"); frase verbal quando "ativado" pode gerar dúvida sobre o que significa exatamente ("Mostrar preço no catálogo"). Escolher uma forma e mantê-la em todos os toggles da mesma tela, sem misturar.
Em positivo: o label nunca começa com negação. "Mostrar preço no catálogo", não "Não ocultar o preço no catálogo".
Sem "ativar/desativar" no label: o toggle já comunica o estado; repetir é redundante. "Preço no catálogo", não "Ativar preço no catálogo".
Sem artigo inicial: as frases nominais não começam com artigo definido. "Notificações por e-mail", não "As notificações por e-mail".

Casos críticos

Caso	O que fazer
Toggle desabilitado por plano, permissões ou dependência	Adicionar o contexto em uma mensagem adjacente, não no label do toggle.
Toggle com um efeito que não é óbvio pelo label	Adicionar um ícone com Tooltip adjacente; o label do toggle não é o lugar para explicar consequências.

Implementação

Instale o componente via terminal.

npm install @nimbus-ds/components

Default

Active

Controlled

Skeleton

import React from "react";
import { Toggle } from "@nimbus-ds/components";

const Example: React.FC = () => (
  <Toggle name="notifications" label="Recibir notificaciones por email" />
);

export default Example;

Props

As propriedades adicionais são repassadas ao elemento <input>. Consulte a documentação do elemento input para ver a lista de atributos aceitos.

Componentes relacionados

Checkbox — Para registrar uma seleção que se confirma ao salvar o formulário, sem efeito imediato.
Radio — Para escolher uma única opção entre várias mutuamente exclusivas.

Toggle

Name	Type	Description
name*	string	The name of the input element.
active	boolean	Sets toggle state to activated or deactivated.
label	string	Text to be rendered inside the component

Toggle.Skeleton

Name	Type	Description
width	string	Width of the skeleton. Useful when the skeleton is inside an inline element with no width of its own.
className	string
data-testid	string	This is an attribute used to identify a DOM node for testing purposes.

Ajude-nos a melhorar a documentação

Encontrou um problema ou tem uma sugestão? Conte para a gente.

Compartilhe seu feedback