ToggleGroup

A compact group of toggle buttons for independent or optional pressed states.

Preview#

Anatomy#

import { ToggleGroup, ToggleGroupItem, ToggleGroupLabel } from "raft-ui";

<ToggleGroup multiple defaultValue={["bold"]} aria-label="Text formatting">
  <ToggleGroupItem value="bold">
    <ToggleGroupLabel>Bold</ToggleGroupLabel>
  </ToggleGroupItem>
</ToggleGroup>

Usage#

Use ToggleGroup when an item may be toggled off. Use SegmentedControl for a persistent one-of-many value that changes a view, filter, or mode.

One or none#

Vertical orientation#

Disabled item#

Disabled group#

API#WIP

ToggleGroup#

Prop	Type	Default	Description
`value`	readonly T[]	—	Pressed item values for controlled use.
`defaultValue`	readonly T[]	—	Initially pressed item values for uncontrolled use.
`onValueChange`	(value: T[], eventDetails: ToggleGroup.ChangeEventDetails) => void	—	Called when the pressed item collection changes.
`multiple`	boolean	false	Allows more than one item to stay pressed.
`orientation`	"horizontal" \| "vertical"	"horizontal"	Controls visual layout and arrow-key navigation.
`loopFocus`	boolean	true	Wraps roving keyboard focus at either end of the group.
`disabled`	boolean	false	Disables every item in the group.
`...props`	Base UI ToggleGroup.Props<T>	—	Native div attributes, render substitution, styling, and ARIA labeling.

ToggleGroupItem#

Prop	Type	Default	Description
`value`	T	—	Required unique value tracked in the parent group's pressed collection.
`disabled`	boolean	false	Disables this item without disabling its siblings.
`onPressedChange`	(pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void	—	Per-item callback fired when this item's pressed state changes, before the group's onValueChange. Use eventDetails.cancel() to reject a single item's press.
`...props`	ToggleGroupItemProps<T>	—	Base UI Toggle props without standalone pressed/defaultPressed state, plus a required value.

ToggleGroupLabel#

Prop	Type	Default	Description
`...props`	ComponentPropsWithRef<"span">	—	Visible item label with truncation and native span attributes.