Components

Toggle group

A set of toggles that share a value. Use single-select for view type, multi-select for orthogonal options like text formatting.

When to usefor 2–5 options where the choice needs to stay visible — view switcher, alignment, density.

Import

import { ToggleGroup, ToggleGroupItem } from "@ravnhq/efni/toggle-group"

Single (view switcher)

const [view, setView] = useState("table");

<ToggleGroup value={view} onValueChange={setView} variant="outline">
  <ToggleGroupItem value="table"><Icon icon={Table} /> Table</ToggleGroupItem>
  <ToggleGroupItem value="board"><Icon icon={LayoutGrid} /> Board</ToggleGroupItem>
  <ToggleGroupItem value="timeline"><Icon icon={Rows} /> Timeline</ToggleGroupItem>
</ToggleGroup>

Multiple (alignment)

<ToggleGroup value={align} onValueChange={setAlign}>
  <ToggleGroupItem value="left"><Icon icon={AlignLeft} /></ToggleGroupItem>
  <ToggleGroupItem value="center"><Icon icon={AlignCenter} /></ToggleGroupItem>
  <ToggleGroupItem value="right"><Icon icon={AlignRight} /></ToggleGroupItem>
</ToggleGroup>

Grouped (no spacing)

<ToggleGroup variant="outline" spacing={0}>…</ToggleGroup>

Accessibility

Key	Action
`ArrowLeft / ArrowRight`	Move between items.
`Enter / Space`	Toggle the focused item.
`Tab`	Enter / leave the group (single tab-stop).

For icon-only items, give each an aria-label.
Base UI's ToggleGroup exposes a spacing prop; set spacing={0} for the segmented-control look.

Guidelines

Reach for single-select when the choices are mutually exclusive — one view at a time.
Use multi-select only when the options are orthogonal (bold + italic + underline).
Keep 2–5 items; more belongs in a Select or Tabs.

Don't

Don't mix icon + label in some items and icon-only in others — pick one shape.
Don't use ToggleGroup for form inputs — use Radio group instead.
Don't allow zero-selected in single mode; guard onValueChange or pass a defaultValue.

Props

Prop	Type	Default	Description
`value`	`readonly Value[]`	—	The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the controlled counterpart of `defaultValue`.
`defaultValue`	`readonly Value[]`	—	The pressed state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the uncontrolled counterpart of `value`.
`onValueChange`	`((groupValue: Value[], eventDetails: ToggleGroup.ChangeEventDetails) => void)`	—	Callback fired when the pressed states of the toggle group changes.
`variant`	`"default" \| "outline"`	`"default"`	Visual style.
`spacing`	`number`	`2`	Set `spacing={0}` for a segmented-control look.
`ToggleGroupItem.value`	`Value`	—	A unique string that identifies the toggle when used inside a toggle group.
`ToggleGroupItem.disabled`	`boolean`	`false`	Whether the component should ignore user interaction.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Lay the group out in a row or a column.
`…props`	`ToggleGroupPrimitive.Props`	—	Everything ToggleGroup passes to the element it renders.