◇

ToggleGroup

2 parts

A set of two-state toggle buttons that behave as one control, with full keyboard roving focus (arrow keys move, Home/End jump to ends, PageUp/PageDown jump to first/last). Set type to 'single' for mutually exclusive options (like a segmented control) or 'multiple' to let several be pressed at once (like a text-formatting bar). When type is omitted it is inferred from the value shape: an array value implies 'multiple', otherwise 'single'. This is the container and state owner: it tracks the pressed value(s) (controlled via v-model or uncontrolled via defaultValue) and provides context to each ToggleGroupItem. With a name, the selected value(s) are also bridged into native form submission. Reach for it to group related toggles such as text alignment, view modes, or formatting options.

Source

Demo

Loading demo…

Anatomy

Import the parts and compose them. Each part forwards attributes to its underlying element.

vue

import {
  ToggleGroupItem,
  ToggleGroupRoot,
} from '@robonen/primitives/forms/toggle-group';

<ToggleGroupRoot>
  <ToggleGroupItem />
</ToggleGroupRoot>

API Reference

ToggleGroupItem

Item

A single toggle button within a `ToggleGroupRoot`, rendered as a native `<button>`. Clicking or pressing Space toggles its `value` on or off; it reflects its pressed state via `data-state` (`on`/`off`) and participates in the group's roving tab order. Must be used inside a `ToggleGroupRoot`, whose `type` determines whether selecting it deselects its siblings. The `value` may be any structural value (string, number, bigint, `null`, or a plain object), compared with deep equality.

Prop	Type	Default	Description
`value`	`ToggleGroupValue`	—	—
`disabled`?	`boolean`	—	—

ToggleGroupRoot

Root

A set of two-state toggle buttons that behave as one control, with full keyboard roving focus (arrow keys move, Home/End jump to ends, PageUp/PageDown jump to first/last). Set `type` to `'single'` for mutually exclusive options (like a segmented control) or `'multiple'` to let several be pressed at once (like a text-formatting bar). When `type` is omitted it is inferred from the value shape: an array value implies `'multiple'`, otherwise `'single'`. This is the container and state owner: it tracks the pressed value(s) (controlled via `v-model` or uncontrolled via `defaultValue`) and provides context to each `ToggleGroupItem`. With a `name`, the selected value(s) are also bridged into native form submission. Reach for it to group related toggles such as text alignment, view modes, or formatting options.

Prop	Type	Default	Description
`type`?	`ToggleGroupType`	—	Whether one (`'single'`) or several (`'multiple'`) items can be pressed. When omitted, inferred from the value shape (array → `'multiple'`).
`defaultValue`?	`ToggleGroupValue \| ToggleGroupValue[]`	—	—
`disabled`?	`boolean`	—	—
`orientation`?	`'horizontal' \| 'vertical'`	—	—
`dir`?	`RovingDirection`	—	Reading direction. When omitted, inherits from a `ConfigProvider` (or LTR).
`loop`?	`boolean`	—	—
`rovingFocus`?	`boolean`	—	—
`name`?	`string`	—	Native input name for form submission. When set, a hidden input mirrors the value.
`required`?	`boolean`	—	Mark the field as required for native form validation.
`modelValue`?	`ToggleGroupValue \| ToggleGroupValue[] \| undefined`	—	Two-way bound value (`v-model`).

Emits

Event	Payload
`update:modelValue`	`[value: ToggleGroupValue \| ToggleGroupValue[] \| undefined]`