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.

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