Toggle Group

Since v0.13.0@kobalte/core/toggle-groupSource

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

Import

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.

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

Example

import { ToggleGroup } from "@kobalte/core/toggle-group";

export function BasicExample() {
  return (
    <ToggleGroup class={style["toggle-group"]}>
      <ToggleGroup.Item
        class={style["toggle-group__item"]}
        value="bold"
        aria-label="Bold"
      >
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="24px"
          height="24px"
          viewBox="0 0 24 24"
        >
          <path
            fill="none"
            stroke="currentColor"
            stroke-linecap="round"
            stroke-linejoin="round"
            stroke-width="2"
            d="M7 5h6a3.5 3.5 0 0 1 0 7H7zm6 7h1a3.5 3.5 0 0 1 0 7H7v-7"
          />
          <title>Bold</title>
        </svg>
      </ToggleGroup.Item>
      <ToggleGroup.Item
        class={style["toggle-group__item"]}
        value="italic"
        aria-label="Italic"
      >
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="24px"
          height="24px"
          viewBox="0 0 24 24"
        >
          <path
            fill="none"
            stroke="currentColor"
            stroke-linecap="round"
            stroke-linejoin="round"
            stroke-width="2"
            d="M11 5h6M7 19h6m1-14l-4 14"
          />
          <title>Italic</title>
        </svg>
      </ToggleGroup.Item>
      <ToggleGroup.Item
        class={style["toggle-group__item"]}
        value="underline"
        aria-label="Underline"
      >
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="24px"
          height="24px"
          viewBox="0 0 24 24"
        >
          <path
            fill="none"
            stroke="currentColor"
            stroke-linecap="round"
            stroke-linejoin="round"
            stroke-width="2"
            d="M7 5v5a5 5 0 0 0 10 0V5M5 19h14"
          />
          <title>Underline</title>
        </svg>
      </ToggleGroup.Item>
    </ToggleGroup>
  );
}

.toggle-group {
  display: flex;
  padding: 0.5rem;
  gap: 0.5rem;
}

.toggle-group[data-orientation="vertical"] {
  flex-direction: column;
}

.toggle-group__item {
  padding: 0.5rem;
  border-radius: 0.5rem;
  appearance: none;
  user-select: none;
  outline: none;
  display: flex;
  justify-content: center;
  align-items: center;
  transition-property: background-color, color;
  transition-duration: 150ms;
  transition-timing-function: ease-in-out;
}

.toggle-group__item:hover {
  background-color: hsl(200 98% 39% / 0.8);
  color: hsla(0 100% 100% / 0.9);
}

[data-theme*="dark"] .toggle-group__item:hover {
  background-color: hsl(200 98% 39% / 0.5);
}

.toggle-group__item[data-pressed] {
  background-color: hsl(200 98% 39%);
  color: hsla(0 100% 100% / 0.9);
}

.toggle-group__item:focus-visible {
  outline: 2px solid hsl(200 98% 39%);
  outline-offset: 2px;
}

Usage

Default pressed

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

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

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.

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.

Last updated: 7/16/26, 7:09 AM

Edit this page on GitHub