Toggle Group

Provides a shared state to a series of toggle buttons.

Import

import { ToggleGroup, Toggle } from '@base-ui/react/toggle-group';

Basic Usage

<ToggleGroup>
  <Toggle value="left">Left</Toggle>
  <Toggle value="center">Center</Toggle>
  <Toggle value="right">Right</Toggle>
</ToggleGroup>

Key Features

Manages state for multiple toggle buttons
Single or multiple selection modes
Controlled and uncontrolled modes
Keyboard navigation (arrow keys)
Horizontal and vertical orientation
Accessible with proper ARIA attributes

Key Props

value

Type: readonly string[] The open state of the toggle group represented by an array of the values of all pressed toggle buttons. Use with onValueChange for controlled mode.

const [value, setValue] = React.useState(['bold']);

<ToggleGroup value={value} onValueChange={setValue}>
  <Toggle value="bold">B</Toggle>
  <Toggle value="italic">I</Toggle>
  <Toggle value="underline">U</Toggle>
</ToggleGroup>

defaultValue

Type: readonly string[] The initial state of the toggle group. Use for uncontrolled mode.

<ToggleGroup defaultValue={['bold', 'italic']}>
  <Toggle value="bold">B</Toggle>
  <Toggle value="italic">I</Toggle>
</ToggleGroup>

onValueChange

Type: (groupValue: string[], eventDetails: ChangeEventDetails) => void Callback fired when the pressed states of the toggle group changes.

<ToggleGroup onValueChange={(value) => console.log('Selected:', value)}>
  {/* toggles */}
</ToggleGroup>

multiple

Type: boolean Default: false When false, only one item in the group can be pressed. When true, multiple items can be pressed.

<ToggleGroup multiple>
  <Toggle value="bold">B</Toggle>
  <Toggle value="italic">I</Toggle>
  <Toggle value="underline">U</Toggle>
</ToggleGroup>

disabled

Type: boolean Default: false Whether the toggle group should ignore user interaction.

orientation

Type: 'horizontal' | 'vertical' Default: 'horizontal' The orientation of the toggle group.

<ToggleGroup orientation="vertical">
  <Toggle value="option1">Option 1</Toggle>
  <Toggle value="option2">Option 2</Toggle>
</ToggleGroup>

loopFocus

Type: boolean Default: true Whether to loop keyboard focus back to the first item when the end is reached.

Styling

Tab Title
Tab Title

<ToggleGroup className="inline-flex rounded-lg border border-gray-300 overflow-hidden">
  <Toggle value="left" className="px-4 py-2 border-r border-gray-300 data-[pressed]:bg-blue-500 data-[pressed]:text-white hover:bg-gray-50">
    Left
  </Toggle>
  <Toggle value="center" className="px-4 py-2 border-r border-gray-300 data-[pressed]:bg-blue-500 data-[pressed]:text-white hover:bg-gray-50">
    Center
  </Toggle>
  <Toggle value="right" className="px-4 py-2 data-[pressed]:bg-blue-500 data-[pressed]:text-white hover:bg-gray-50">
    Right
  </Toggle>
</ToggleGroup>

<ToggleGroup className={styles.group}>
  <Toggle value="left" className={styles.toggle}>Left</Toggle>
  <Toggle value="center" className={styles.toggle}>Center</Toggle>
  <Toggle value="right" className={styles.toggle}>Right</Toggle>
</ToggleGroup>

.group {
  display: inline-flex;
  border: 1px solid #d1d5db;
  border-radius: 0.5rem;
  overflow: hidden;
}

.toggle {
  padding: 0.5rem 1rem;
  border-right: 1px solid #d1d5db;
}

.toggle:last-child {
  border-right: none;
}

.toggle:hover {
  background-color: #f9fafb;
}

.toggle[data-pressed] {
  background-color: #3b82f6;
  color: white;
}

Common Patterns

Text Alignment

function TextAlignmentToggle() {
  const [alignment, setAlignment] = React.useState(['left']);

  return (
    <ToggleGroup value={alignment} onValueChange={setAlignment}>
      <Toggle value="left" className="px-3 py-2">
        <AlignLeftIcon />
      </Toggle>
      <Toggle value="center" className="px-3 py-2">
        <AlignCenterIcon />
      </Toggle>
      <Toggle value="right" className="px-3 py-2">
        <AlignRightIcon />
      </Toggle>
      <Toggle value="justify" className="px-3 py-2">
        <AlignJustifyIcon />
      </Toggle>
    </ToggleGroup>
  );
}

Text Formatting (Multiple)

function TextFormattingToolbar() {
  const [formats, setFormats] = React.useState([]);

  return (
    <ToggleGroup multiple value={formats} onValueChange={setFormats}>
      <Toggle value="bold" className="px-3 py-2 font-bold">
        B
      </Toggle>
      <Toggle value="italic" className="px-3 py-2 italic">
        I
      </Toggle>
      <Toggle value="underline" className="px-3 py-2 underline">
        U
      </Toggle>
      <Toggle value="strikethrough" className="px-3 py-2 line-through">
        S
      </Toggle>
    </ToggleGroup>
  );
}

View Mode Selector

function ViewModeSelector() {
  const [view, setView] = React.useState(['grid']);

  return (
    <ToggleGroup value={view} onValueChange={setView} className="inline-flex rounded-lg border">
      <Toggle value="list" className="px-4 py-2 flex items-center gap-2">
        <ListIcon className="w-4 h-4" />
        List
      </Toggle>
      <Toggle value="grid" className="px-4 py-2 flex items-center gap-2">
        <GridIcon className="w-4 h-4" />
        Grid
      </Toggle>
      <Toggle value="table" className="px-4 py-2 flex items-center gap-2">
        <TableIcon className="w-4 h-4" />
        Table
      </Toggle>
    </ToggleGroup>
  );
}

Vertical Toggle Group

<ToggleGroup orientation="vertical" className="inline-flex flex-col border rounded-lg">
  <Toggle value="option1" className="px-4 py-2 border-b text-left">
    Option 1
  </Toggle>
  <Toggle value="option2" className="px-4 py-2 border-b text-left">
    Option 2
  </Toggle>
  <Toggle value="option3" className="px-4 py-2 text-left">
    Option 3
  </Toggle>
</ToggleGroup>

Size Selector

function SizeSelector() {
  const [size, setSize] = React.useState(['m']);

  const sizes = [
    { value: 'xs', label: 'XS' },
    { value: 's', label: 'S' },
    { value: 'm', label: 'M' },
    { value: 'l', label: 'L' },
    { value: 'xl', label: 'XL' },
  ];

  return (
    <div>
      <label className="block mb-2 font-medium">Select Size</label>
      <ToggleGroup value={size} onValueChange={setSize} className="inline-flex gap-2">
        {sizes.map((s) => (
          <Toggle
            key={s.value}
            value={s.value}
            className="w-12 h-12 rounded border-2 border-gray-300 data-[pressed]:border-blue-500 data-[pressed]:bg-blue-50"
          >
            {s.label}
          </Toggle>
        ))}
      </ToggleGroup>
    </div>
  );
}

Getting Started

Handbook

Inputs

Data Display

Navigation

Overlays

Forms

Layout

Utilities

Import

Basic Usage

Key Features

Key Props

value

defaultValue

onValueChange

multiple

disabled

orientation

loopFocus

Styling

Common Patterns

Text Alignment

Text Formatting (Multiple)

View Mode Selector

Vertical Toggle Group

Size Selector

​Import

​Basic Usage

​Key Features

​Key Props

​value

​defaultValue

​onValueChange

​multiple

​disabled

​orientation

​loopFocus

​Styling

​Common Patterns

​Text Alignment

​Text Formatting (Multiple)

​View Mode Selector

​Vertical Toggle Group

​Size Selector

Import

Basic Usage

Key Features

Key Props

value

defaultValue

onValueChange

multiple

disabled

orientation

loopFocus

Styling

Common Patterns

Text Alignment

Text Formatting (Multiple)

View Mode Selector

Vertical Toggle Group

Size Selector