Home/Componentes/Toggle & Toggle Group

Toggle & Toggle Group

Interactive

Botões de alternância para estados binários e seleção de opções.

Preview

Visualização dos componentes Toggle e Toggle Group

Toggle Simples

Toggle Group

Instalação

Via CLI (Recomendado)

1. Inicializar (primeira vez)

npx @scmposs/hollow-ui init
npx @scmposs/hollow-ui setup

2. Adicionar componente

npx @scmposs/hollow-ui add toggle

Os comandos init e setup fazem o pré-setup (necessário apenas uma vez). Se você rodar add sem isso, a CLI executa o setup automaticamente.

Via NPM

Instalar pacote completo

npm install @scmposs/hollow-ui@latest

Instala todos os componentes como dependência do projeto.

Instalação

Via CLI (Recomendado)

1. Inicializar (primeira vez)

npx @scmposs/hollow-ui init
npx @scmposs/hollow-ui setup

2. Adicionar componente

npx @scmposs/hollow-ui add toggle-group

Os comandos init e setup fazem o pré-setup (necessário apenas uma vez). Se você rodar add sem isso, a CLI executa o setup automaticamente.

Via NPM

Instalar pacote completo

npm install @scmposs/hollow-ui@latest

Instala todos os componentes como dependência do projeto.

Uso Básico

Toggle

import { Toggle } from "@scmposs/hollow-ui"
import { Bold } from "lucide-react"

<Toggle aria-label="Toggle bold">
  <Bold className="h-4 w-4" />
</Toggle>

Toggle Group

import { ToggleGroup, ToggleGroupItem } from "@scmposs/hollow-ui"

<ToggleGroup type="single">
  <ToggleGroupItem value="left">Left</ToggleGroupItem>
  <ToggleGroupItem value="center">Center</ToggleGroupItem>
  <ToggleGroupItem value="right">Right</ToggleGroupItem>
</ToggleGroup>

Exemplos

Diferentes casos de uso dos componentes Toggle e Toggle Group

Toggle Básico

Estado: Normal

const [pressed, setPressed] = useState(false);

<Toggle
  pressed={pressed}
  onPressedChange={setPressed}
  aria-label="Toggle feature"
>
  {pressed ? "Ativado" : "Desativado"}
</Toggle>

Toggle com Ícones

import { Bold, Italic, Underline } from "lucide-react"

<Toggle aria-label="Toggle bold">
  <Bold className="h-4 w-4" />
</Toggle>
<Toggle aria-label="Toggle italic">
  <Italic className="h-4 w-4" />
</Toggle>
<Toggle aria-label="Toggle underline">
  <Underline className="h-4 w-4" />
</Toggle>

Variantes do Toggle

Default

Outline

<Toggle variant="default">
  <Bold className="h-4 w-4" />
</Toggle>

<Toggle variant="outline">
  <Bold className="h-4 w-4" />
</Toggle>

Tamanhos do Toggle

Small

Default

Large

<Toggle size="sm">
  <Bold className="h-3 w-3" />
</Toggle>

<Toggle size="default">
  <Bold className="h-4 w-4" />
</Toggle>

<Toggle size="lg">
  <Bold className="h-5 w-5" />
</Toggle>

ToggleGroup - Seleção Única

Alinhamento selecionado: left

const [alignment, setAlignment] = useState("left");

<ToggleGroup
  type="single"
  value={alignment}
  onValueChange={(value) => value && setAlignment(value)}
>
  <ToggleGroupItem value="left" aria-label="Align left">
    <AlignLeft className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="center" aria-label="Align center">
    <AlignCenter className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="right" aria-label="Align right">
    <AlignRight className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="justify" aria-label="Align justify">
    <AlignJustify className="h-4 w-4" />
  </ToggleGroupItem>
</ToggleGroup>

ToggleGroup - Seleção Múltipla

Formatação ativa: Nenhuma

const [formatting, setFormatting] = useState<string[]>([]);

<ToggleGroup
  type="multiple"
  value={formatting}
  onValueChange={setFormatting}
>
  <ToggleGroupItem value="bold" aria-label="Toggle bold">
    <Bold className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Toggle italic">
    <Italic className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="underline" aria-label="Toggle underline">
    <Underline className="h-4 w-4" />
  </ToggleGroupItem>
</ToggleGroup>

ToggleGroup - Variante Outline

<ToggleGroup type="single" variant="outline">
  <ToggleGroupItem value="left">
    <AlignLeft className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="center">
    <AlignCenter className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="right">
    <AlignRight className="h-4 w-4" />
  </ToggleGroupItem>
</ToggleGroup>

Estados Desabilitados

Toggle Desabilitado

ToggleGroup Desabilitado

<Toggle disabled>
  <Bold className="h-4 w-4" />
</Toggle>

<ToggleGroup type="single" disabled>
  <ToggleGroupItem value="left">
    <AlignLeft className="h-4 w-4" />
  </ToggleGroupItem>
  <ToggleGroupItem value="center">
    <AlignCenter className="h-4 w-4" />
  </ToggleGroupItem>
</ToggleGroup>

Propriedades - Toggle

Props disponíveis para o componente Toggle

Prop	Tipo	Padrão	Descrição
variant	"default" \| "outline"	"default"	Estilo visual do toggle
size	"default" \| "sm" \| "lg"	"default"	Tamanho do toggle
pressed	boolean	-	Estado pressionado (controlado)
defaultPressed	boolean	false	Estado pressionado inicial (não controlado)
onPressedChange	(pressed: boolean) => void	-	Callback quando o estado muda
disabled	boolean	false	Desabilita o toggle
className	string	-	Classes CSS customizadas

Nota: Baseado em Radix UI Toggle. O componente exporta também toggleVariants para uso customizado com cva.

Propriedades - ToggleGroup

Props disponíveis para o componente ToggleGroup

Prop	Tipo	Padrão	Descrição
type	"single" \| "multiple"	-	Modo de seleção (obrigatório)
value	string \| string[]	-	Valor(es) selecionado(s) (controlado)
defaultValue	string \| string[]	-	Valor(es) inicial(is) (não controlado)
onValueChange	(value) => void	-	Callback quando a seleção muda
variant	"default" \| "outline"	"default"	Estilo visual dos itens
size	"default" \| "sm" \| "lg"	"default"	Tamanho dos itens
disabled	boolean	false	Desabilita todos os itens
className	string	-	Classes CSS customizadas

Propriedades - ToggleGroupItem

Props disponíveis para o componente ToggleGroupItem

Prop	Tipo	Padrão	Descrição
value	string	-	Valor único do item (obrigatório)
variant	"default" \| "outline"	Herda do grupo	Sobrescreve variante do grupo
size	"default" \| "sm" \| "lg"	Herda do grupo	Sobrescreve tamanho do grupo
disabled	boolean	false	Desabilita apenas este item
className	string	-	Classes CSS customizadas

Nota: Baseado em Radix UI Toggle Group. Use dentro de um componente ToggleGroup.

Diretrizes de Uso

✅ Quando usar

Para opções de formatação de texto (negrito, itálico, etc.)
Configurações de visualização (grid/lista)
Alinhamento de conteúdo
Filtros que podem ser ativados/desativados
Estados binários visualmente evidentes

❌ Quando evitar

Para ações que não são estados (use Button)
Em formulários complexos (use Checkbox ou Switch)
Para muitas opções (use Select ou RadioGroup)
Quando o estado não é imediatamente visível

💡 Dicas

Sempre forneça aria-label descritivo para ícones
Use ToggleGroup para opções relacionadas
type="single" quando apenas uma opção pode estar ativa
type="multiple" quando várias opções podem estar ativas simultaneamente
Prefira ícones reconhecíveis do lucide-react
Mantenha o estado pressionado visualmente claro

Acessibilidade

Sempre use aria-label: Especialmente importante quando o toggle contém apenas ícones
Estado pressionado: Automaticamente exposto via aria-pressed
Navegação por teclado: Space ou Enter para ativar/desativar
ToggleGroup: Suporta navegação com setas (←→) entre itens
Foco visível: Indicador de foco para navegação por teclado
Estados disabled: Respeitam semântica HTML e são anunciados por leitores de tela
Radix UI: Baseado em componentes primitivos com suporte completo a ARIA