Toggle Group

Headless toggle group primitives for single and multiple selection patterns.

Stable direction
@lattice-ui/toggle-group

Part of the stable direction toward v1.0.

What It Is For

Use ToggleGroup for pill bars, formatting controls, and compact segmented selectors where buttons should show pressed state.

It bridges the gap between a lone Switch and a full RadioGroup, with both single and multiple selection modes.

Preview size

Live demo is experimental and may contain bugs.

Install

Global CLI command: lattice add toggle-group

Monorepo local script

Use your package manager wrapper when running the local lattice command.

pnpm lattice add toggle-group

npm package: @lattice-ui/toggle-group

Peer dependencies

  • @rbxts/react
  • @rbxts/react-roblox

Public Exports

  • ToggleGroup
  • ToggleGroup.Root
  • ToggleGroup.Item

State Model

  • ToggleGroup.Root switches between single and multiple selection models through the required type prop.
  • The value shape follows that selection model: a string or undefined for single, an array for multiple.
  • Pressed state is computed centrally, and both group-level and item-level disabled flags participate in interaction rules.

Key API

ToggleGroup.Root

Use type, value, defaultValue, and onValueChange to define whether the group behaves like a segmented selector or a pressed-state toolbar.

ToggleGroup.Item

Each item needs a stable value; disabled removes it from toggling without changing the rest of the group.

Composition Patterns

Single-choice segmented controls

Use type="single" when the control should feel like a compact alternative to radio buttons.

Pressed formatting toolbars

Use type="multiple" when several pressed states may be active at once, such as bold/italic/underline controls.

Cautions / Limits

  • The controlled value shape changes with type, so avoid sharing one state variable between single and multiple groups without normalizing it first.
  • Use RadioGroup when the options should stay visible but read more like a classic form control than a pressed button bar.