@data-slot/toggle-group

A group of toggle buttons with shared state, supporting single or multiple selection.

Installation

bun add @data-slot/toggle-group

Usage

Basic Markup

<!-- Single selection (default) -->
<div data-slot="toggle-group" data-default-value="center">
  <button data-slot="toggle-group-item" data-value="left">Left</button>
  <button data-slot="toggle-group-item" data-value="center">Center</button>
  <button data-slot="toggle-group-item" data-value="right">Right</button>
</div>

<!-- Multiple selection -->
<div data-slot="toggle-group" data-multiple data-default-value="bold italic">
  <button data-slot="toggle-group-item" data-value="bold">B</button>
  <button data-slot="toggle-group-item" data-value="italic">I</button>
  <button data-slot="toggle-group-item" data-value="underline">U</button>
</div>

JavaScript

import { create, createToggleGroup } from "@data-slot/toggle-group";

// Auto-discover and bind all toggle-group elements
const controllers = create();

// Or target a specific element
const group = createToggleGroup(element, {
  defaultValue: "center",
  multiple: false,
  orientation: "horizontal",
  loop: true,
  onValueChange: (value) => console.log(value),
});

// Programmatic control
group.setValue("left");
group.toggle("bold");
console.log(group.value); // ["left"]

// Cleanup
group.destroy();

API

Initialization

create(scope?)

Find and bind uninitialized [data-slot="toggle-group"] descendants of scope (defaults to document). Returns ToggleGroupController[] for newly bound roots. To initialize the scope element itself, use createToggleGroup.

import { create } from "@data-slot/toggle-group";

const controllers = create();

createToggleGroup(root, options?)

Create a ToggleGroupController for one root element. JavaScript options take precedence over the corresponding data attributes. Calling this again for a bound root returns its existing controller; destroy it before rebinding with new options.

import { createToggleGroup } from "@data-slot/toggle-group";

const controller = createToggleGroup(element, {});

Slots

Runtime Slots

• toggle-group - Root element that manages single or multiple selection and keyboard navigation between items.
• toggle-group-item - Toggle button inside the group, identified by a unique data-value; receives aria-pressed and data-state as its selection changes.

Data Attributes

Root Element

Item Elements

State Attributes (set by component)

Options

Controller

Controller methods work while the group is disabled. User interaction and toggle-group:set are blocked while disabled.

Events

Outbound Events

// Listen for changes
root.addEventListener("toggle-group:change", (e) => {
  console.log(e.detail.value); // string[]
});

Inbound Events

// Set selection from outside
root.dispatchEvent(new CustomEvent("toggle-group:set", {
  detail: { value: "bold" }
}));

// Set multiple values
root.dispatchEvent(new CustomEvent("toggle-group:set", {
  detail: { value: ["bold", "italic"] }
}));

Note: Blocked when group is disabled.

Deprecated Shapes

The following shapes are deprecated and will be removed in v1.0:

// Deprecated: bare string
root.dispatchEvent(new CustomEvent("toggle-group:set", {
  detail: "bold"
}));

// Deprecated: bare array
root.dispatchEvent(new CustomEvent("toggle-group:set", {
  detail: ["bold", "italic"]
}));

Use { value: ... } instead.

Styling

/* Style pressed items */
[data-slot="toggle-group-item"][data-state="on"] {
  background: #333;
  color: white;
}

/* Style disabled items */
[data-slot="toggle-group-item"][aria-disabled="true"] {
  opacity: 0.5;
  cursor: not-allowed;
}

Keyboard Navigation

Accessibility

• Root has role="group"
• Items have aria-pressed attribute
• Disabled items have aria-disabled="true" and native disabled
• Supports roving tabindex for keyboard navigation
• Add aria-label or aria-labelledby to root for context