Kobalte.v0.13.4

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).

PropDescription
valuestring | string[]
The controlled pressed state of the toggle button.
defaultValuestring | 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.
multipleboolean
Whether the toggle group allows multi-selection.
orientation'horizontal' | 'vertical'
The orientation of the toggle group.
disabledboolean
Whether toggle group should be disabled.
Data attributeDescription
data-orientation='horizontal'Present when the separator has horizontal orientation.
data-orientation='vertical'Present when the separator has vertical orientation.

ToggleGroup.Item

PropDescription
valuestring
A unique value for the item.
disabledboolean
Whether the item is disabled.
childrenJSX.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 PropDescription
pressedAccessor<boolean>
Whether the toggle button is on (pressed) or off (not pressed).
Data attributeDescription
data-orientation='horizontal'Present when the separator has horizontal orientation.
data-orientation='vertical'Present when the separator has vertical orientation.
data-disabledPresent when the accordion item is disabled.
data-pressedPresent when the toggle button is on (pressed).

Rendered elements

ComponentDefault rendered element
ToggleGroupdiv
ToggleGroup.Itembutton

Accessibility

Keyboard Interactions

KeyDescription
TabMove focus to either the pressed item or the first item in the group.
ArrowDownIf orientation is vertical, moves focus to the next item.
ArrowRightIf orientation is horizontal, Moves focus to the next item.
ArrowUpIf orientation is vertical, moves focus to the previous item.
ArrowLeftIf orientation is vertical, moves focus to the previous item.
HomeMoves focus to the first item.
EndMoves focus to the last item.
EnterActivates/deactivates the item.
SpaceActivates/deactivates the item.