Toggle Group

A set of two-state buttons that can be toggled on (pressed) or off (not pressed).

Import

ts
import { ToggleGroup } from "@kobalte/core/toggle-group";
// or
import { Root, Item, ... } from "@kobalte/core/toggle-group";
// or (deprecated)
import { ToggleGroup } from "@kobalte/core";

ts
import { ToggleGroup } from "@kobalte/core/toggle-group";
// or
import { Root, Item, ... } from "@kobalte/core/toggle-group";
// or (deprecated)
import { ToggleGroup } from "@kobalte/core";

Features

Supports horizontal/vertical orientation.
Keyboard event support for Space and Enter keys.
Can be controlled or uncontrolled.

Anatomy

The toggle group consists of:

ToggleGroup: the root container for a toggle group.

The toggle item consists of:

ToggleGroup.Item: the root container for a toggle button.

tsx
<ToggleGroup>
	<ToggleGroup.Item />
</ToggleGroup>

tsx
<ToggleGroup>
	<ToggleGroup.Item />
</ToggleGroup>

Example

Usage

Default pressed

An initial, uncontrolled value can be provided using the defaultValue prop.

tsx
<ToggleGroup defaultValue="underline">
	<ToggleGroup.Item value="bold" aria-label="Bold">
		<BoldIcon />
	</ToggleGroup.Item>
	<ToggleGroup.Item value="italic" aria-label="Italic">
		<ItalicIcon />
	</ToggleGroup.Item>
	<ToggleGroup.Item value="underline" aria-label="Underline">
		<UnderlineIcon />
	</ToggleGroup.Item>
</ToggleGroup>

tsx
<ToggleGroup defaultValue="underline">
	<ToggleGroup.Item value="bold" aria-label="Bold">
		<BoldIcon />
	</ToggleGroup.Item>
	<ToggleGroup.Item value="italic" aria-label="Italic">
		<ItalicIcon />
	</ToggleGroup.Item>
	<ToggleGroup.Item value="underline" aria-label="Underline">
		<UnderlineIcon />
	</ToggleGroup.Item>
</ToggleGroup>

Controlled pressed

The value prop can be used to make the pressed state controlled. The onChange event is fired when the user toggle the button, and receives the new value.

Your text style is: bold.

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal("underline");
	return (
		<>
			<ToggleGroup value={value()} onChange={setValue}>
				...
			</ToggleGroup>
			<p>Your text style is: {value()}.</p>
		</>
	);
}

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
	const [value, setValue] = createSignal("underline");
	return (
		<>
			<ToggleGroup value={value()} onChange={setValue}>
				...
			</ToggleGroup>
			<p>Your text style is: {value()}.</p>
		</>
	);
}

Multiple selection

The multiple prop can be used to create a select that allow multi-selection.

tsx
import { createSignal } from "solid-js";
function MultipleSelectionExample() {
	const [values, setValues] = createSignal(["bold", "underline"]);
	return (
		<ToggleGroup class="toggle-group" value={values()} onChange={setValues}>
			<ToggleGroup.Item class="toggle-group__item" value="bold" aria-label="Bold">
				<BoldIcon />
			</ToggleGroup.Item>
			<ToggleGroup.Item class="toggle-group__item" value="italic" aria-label="Italic">
				<ItalicIcon />
			</ToggleGroup.Item>
			<ToggleGroup.Item class="toggle-group__item" value="underline" aria-label="Underline">
				<UnderlineIcon />
			</ToggleGroup.Item>
		</ToggleGroup>
	);
}

tsx
import { createSignal } from "solid-js";
function MultipleSelectionExample() {
	const [values, setValues] = createSignal(["bold", "underline"]);
	return (
		<ToggleGroup class="toggle-group" value={values()} onChange={setValues}>
			<ToggleGroup.Item class="toggle-group__item" value="bold" aria-label="Bold">
				<BoldIcon />
			</ToggleGroup.Item>
			<ToggleGroup.Item class="toggle-group__item" value="italic" aria-label="Italic">
				<ItalicIcon />
			</ToggleGroup.Item>
			<ToggleGroup.Item class="toggle-group__item" value="underline" aria-label="Underline">
				<UnderlineIcon />
			</ToggleGroup.Item>
		</ToggleGroup>
	);
}

API Reference

ToggleGroup

ToggleGroup is equivalent to the Root import from @kobalte/core/toggle-group (and deprecated ToggleGroup.Root).

Prop	Description
value	`string \| string[]` The controlled pressed state of the toggle button.
defaultValue	`string \| string[]` The default pressed state when initially rendered. Useful when you do not need to control the pressed state.
onChange	`(value: string \| string[]) => void` Event handler called when the pressed state of an item changes.
multiple	`boolean` Whether the toggle group allows multi-selection.
orientation	`'horizontal' \| 'vertical'` The orientation of the toggle group.
disabled	`boolean` Whether toggle group should be disabled.

Data attribute	Description
data-orientation='horizontal'	Present when the separator has horizontal orientation.
data-orientation='vertical'	Present when the separator has vertical orientation.

ToggleGroup.Item

Prop	Description
value	`string` A unique value for the item.
disabled	`boolean` Whether the item is disabled.
children	`JSX.Element \| (state: ToggleButtonState) => JSX.Element` The children of the item. Can be a `JSX.Element` or a render prop for having access to the internal state.

Render Prop	Description
pressed	`Accessor<boolean>` Whether the toggle button is on (pressed) or off (not pressed).

Data attribute	Description
data-orientation='horizontal'	Present when the separator has horizontal orientation.
data-orientation='vertical'	Present when the separator has vertical orientation.
data-disabled	Present when the accordion item is disabled.
data-pressed	Present when the toggle button is on (pressed).

Rendered elements

Component	Default rendered element
`ToggleGroup`	`div`
`ToggleGroup.Item`	`button`

Accessibility

Keyboard Interactions

Key	Description
`Tab`	Move focus to either the pressed item or the first item in the group.
`ArrowDown`	If orientation is vertical, moves focus to the next item.
`ArrowRight`	If orientation is horizontal, Moves focus to the next item.
`ArrowUp`	If orientation is vertical, moves focus to the previous item.
`ArrowLeft`	If orientation is vertical, moves focus to the previous item.
`Home`	Moves focus to the first item.
`End`	Moves focus to the last item.
`Enter`	Activates/deactivates the item.
`Space`	Activates/deactivates the item.