Toggle
Botão liga/desliga para alternar uma opção, e ToggleGroup para escolher entre opções agrupadas.
'use client';
import { Heart } from 'lucide-react';
import { Toggle } from '@/components/ui/toggle';
export default function ToggleDemo() {
return (
<Toggle aria-label="Favoritar produto">
<Heart />
</Toggle>
);
}Instalação
npx shadcn@latest add @lenstech/toggleO mesmo arquivo exporta Toggle e ToggleGroup.
Uso
import { Toggle, ToggleGroup } from "@/components/ui/toggle"<Toggle aria-label="Favoritar produto">
<Heart />
</Toggle>
<ToggleGroup aria-label="Visualização" defaultSelectedKeys={["grade"]}>
<Toggle id="grade">Grade</Toggle>
<Toggle id="lista">Lista</Toggle>
</ToggleGroup>Só ícone? Informe aria-label
O leitor de tela anuncia o nome e o estado ("pressionado"/"não pressionado"). Sem texto visível,
o aria-label é obrigatório.
Exemplos
Contorno
'use client';
import { Bold, Italic, Underline } from 'lucide-react';
import { Toggle } from '@/components/ui/toggle';
export default function ToggleOutline() {
return (
<div className="flex items-center gap-2">
<Toggle variant="outline" aria-label="Negrito">
<Bold />
</Toggle>
<Toggle variant="outline" aria-label="Itálico">
<Italic />
</Toggle>
<Toggle variant="outline" defaultSelected aria-label="Sublinhado">
<Underline />
</Toggle>
</div>
);
}Com texto (controlado)
Use isSelected + onChange para ler o estado — aqui, um filtro rápido de produtos.
Mostrando todos os 64 produtos.
'use client';
import { useState } from 'react';
import { Truck } from 'lucide-react';
import { Toggle } from '@/components/ui/toggle';
export default function ToggleWithText() {
const [freteGratis, setFreteGratis] = useState(false);
return (
<div className="flex flex-col items-center gap-3">
<Toggle variant="outline" isSelected={freteGratis} onChange={setFreteGratis}>
<Truck /> Só frete grátis
</Toggle>
<p className="text-sm text-muted-foreground">
{freteGratis ? 'Mostrando 18 produtos com frete grátis.' : 'Mostrando todos os 64 produtos.'}
</p>
</div>
);
}Tamanhos e desabilitado
'use client';
import { Star } from 'lucide-react';
import { Toggle } from '@/components/ui/toggle';
export default function ToggleSizes() {
return (
<div className="flex items-center gap-2">
<Toggle size="sm" variant="outline" aria-label="Destacar (pequeno)">
<Star />
</Toggle>
<Toggle variant="outline" aria-label="Destacar (padrão)">
<Star />
</Toggle>
<Toggle size="lg" variant="outline" aria-label="Destacar (grande)">
<Star />
</Toggle>
<Toggle variant="outline" isDisabled aria-label="Destacar (desabilitado)">
<Star />
</Toggle>
</div>
);
}ToggleGroup — seleção única
Por padrão o grupo aceita uma opção (selectionMode="single"). disallowEmptySelection impede desmarcar a opção ativa. Cada Toggle do grupo precisa de id.
Exibindo em grade.
'use client';
import { useState } from 'react';
import type { Key } from 'react-aria-components';
import { LayoutGrid, List } from 'lucide-react';
import { Toggle, ToggleGroup } from '@/components/ui/toggle';
export default function ToggleGroupSingle() {
const [visualizacao, setVisualizacao] = useState<Set<Key>>(new Set(['grade']));
return (
<div className="flex flex-col items-center gap-3">
<ToggleGroup
aria-label="Visualização dos produtos"
variant="outline"
disallowEmptySelection
selectedKeys={visualizacao}
onSelectionChange={setVisualizacao}
>
<Toggle id="grade" aria-label="Grade">
<LayoutGrid />
</Toggle>
<Toggle id="lista" aria-label="Lista">
<List />
</Toggle>
</ToggleGroup>
<p className="text-sm text-muted-foreground">
Exibindo em {visualizacao.has('grade') ? 'grade' : 'lista'}.
</p>
</div>
);
}ToggleGroup — seleção múltipla
'use client';
import { Toggle, ToggleGroup } from '@/components/ui/toggle';
export default function ToggleGroupMultiple() {
return (
<ToggleGroup aria-label="Dias de atendimento" selectionMode="multiple" defaultSelectedKeys={['seg', 'qua', 'sex']}>
<Toggle id="seg">Seg</Toggle>
<Toggle id="ter">Ter</Toggle>
<Toggle id="qua">Qua</Toggle>
<Toggle id="qui">Qui</Toggle>
<Toggle id="sex">Sex</Toggle>
<Toggle id="sab">Sáb</Toggle>
</ToggleGroup>
);
}variant e size no grupo
Dentro de um ToggleGroup, variant e size definidos no grupo têm prioridade sobre os de cada Toggle.
Quando usar
- Use
Togglepara alternar formatação ou visualização (negrito, favoritar, "só frete grátis"). - Use
ToggleGrouppara poucas opções mutuamente exclusivas e visuais (grade/lista, dias da semana). - Não use para configurações que salvam na hora (ex.: "receber lembretes") — prefira
Switch. - Não use para escolher entre muitas opções — prefira
SelectouRadioGroup; para disparar ações,Button.
API
Toggle
Aceita todas as props do ToggleButton do React Aria, mais:
Prop
Type
ToggleGroup
Aceita todas as props do ToggleButtonGroup do React Aria, mais:
Prop
Type