Capítulo 75 de 108

Toggle Group

Core Idea

A set of related two-state buttons toggled together (e.g. text formatting, view selectors). Supports single or multiple selection and horizontal/vertical orientation.

Key Concepts

  • multiple: boolean prop enabling multi-select (several items pressed at once); omit for single-select behavior.
  • variant: "outline" for bordered items.
  • size: sm / default / lg applied to all items.
  • spacing: numeric prop (e.g. spacing={2}) controlling gap between items; default changed from 0 to 2 (2026-05-17 changelog) — use spacing={0} for connected/no-gap items.
  • orientation: "vertical" for stacked toggles.
  • value / onValueChange / defaultValue: array-based controlled/uncontrolled state (values are arrays even in single mode when controlled directly, e.g. value={[fontWeight]}).
  • disabled: disables the whole group.

Code Examples

<ToggleGroup variant="outline" multiple>
  <ToggleGroupItem value="bold" aria-label="Toggle bold"><Bold /></ToggleGroupItem>
  <ToggleGroupItem value="italic" aria-label="Toggle italic"><Italic /></ToggleGroupItem>
  <ToggleGroupItem value="strikethrough" aria-label="Toggle strikethrough"><Underline /></ToggleGroupItem>
</ToggleGroup>
  • O que demonstra: Multi-seleção de opções de formatação independentes.
const [fontWeight, setFontWeight] = React.useState("normal")
<ToggleGroup value={[fontWeight]} onValueChange={(value) => setFontWeight(value[0])} variant="outline" spacing={2} size="lg">
  <ToggleGroupItem value="light" aria-label="Light">...</ToggleGroupItem>
  ...
</ToggleGroup>
  • O que demonstra: Estado controlado tratando value/onValueChange como array mesmo em seleção única.

Composition

ToggleGroup
├── ToggleGroupItem
└── ToggleGroupItem

Reference Tables

PropType/Values
multipleboolean
variantdefault, outline
sizesm, default, lg
spacingnumber (default 2 since 2026-05-17)
orientationhorizontal (default), vertical

Anti-patterns

  • Assumir spacing padrão 0 em código antigo: mudou pra 2; se depender de itens colados, defina spacing={0} explicitamente.

Key Takeaways

  1. onValueChange sempre recebe/retorna array, mesmo em seleção única (value[0]).
  2. multiple habilita seleção múltipla; sem ela o grupo é exclusivo (single-select).
  3. spacing={0} reproduz o comportamento antigo de itens conectados sem espaço.
  4. orientation="vertical" empilha os itens, útil pra menus laterais de opções.

Connects To

  • Toggle: item individual usado dentro do grupo.
  • Field: comum envolver ToggleGroup em Field/FieldLabel/FieldDescription para formulários.
AnteriorTogglePróximoPagination