ToggleGroup

ToggleGroup provides a set of two-state buttons that can either be off (not pressed) or on (pressed).

'use client';
import * as React from 'react';
import { ToggleGroup } from '@base-ui-components/react/toggle-group';
import { Toggle } from '@base-ui-components/react/toggle';
import classes from './styles.module.css';

export default function ToggleGroupIntroduction() {
  const [value, setValue] = React.useState(['align-center']);
  return (
    <ToggleGroup
      className={classes.root}
      value={value}
      onValueChange={(newValue) => {
        if (newValue.length > 0) {
          setValue(newValue);
        }
      }}
      aria-label="Text alignment"
    >
      <Toggle className={classes.button} value="align-left" aria-label="Align left">
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="24"
          height="24"
          viewBox="0 0 24 24"
          className={classes.icon}
        >
          <line x1="17" y1="10" x2="3" y2="10" />
          <line x1="21" y1="6" x2="3" y2="6" />
          <line x1="21" y1="14" x2="3" y2="14" />
          <line x1="17" y1="18" x2="3" y2="18" />
        </svg>
      </Toggle>

      <Toggle
        className={classes.button}
        value="align-center"
        aria-label="Align center"
      >
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="24"
          height="24"
          viewBox="0 0 24 24"
          className={classes.icon}
        >
          <line x1="18" y1="10" x2="6" y2="10" />
          <line x1="21" y1="6" x2="3" y2="6" />
          <line x1="21" y1="14" x2="3" y2="14" />
          <line x1="18" y1="18" x2="6" y2="18" />
        </svg>
      </Toggle>

      <Toggle
        className={classes.button}
        value="align-right"
        aria-label="Align right"
      >
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="24"
          height="24"
          viewBox="0 0 24 24"
          className={classes.icon}
        >
          <line x1="21" y1="10" x2="7" y2="10" />
          <line x1="21" y1="6" x2="3" y2="6" />
          <line x1="21" y1="14" x2="3" y2="14" />
          <line x1="21" y1="18" x2="7" y2="18" />
        </svg>
      </Toggle>
    </ToggleGroup>
  );
}

Installation

Base UI components are all available as a single package.

npm install @base-ui-components/react

Once you have the package installed, import the component.

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

Anatomy

ToggleGroups are composed with two components:

<ToggleGroup /> is the outer component that wraps a set of toggles
<Toggle />s renders the <button>

<ToggleGroup>
  <Toggle value="bold">Bold</Toggle>
  <Toggle value="italics">Italics</Toggle>
  <Toggle value="underline">Underline</Toggle>
</ToggleGroup>

Value

Each Item in the group must be given a unique value, e.g. a string like 'bold', 'italics' in the examples above.

Uncontrolled

When uncontrolled, use the defaultValue prop to set the initial state of the group:

// only the "Italics" button is initially pressed
<ToggleGroup defaultValue={['italics']}>
  <Toggle value="bold">Bold</Toggle>
  <Toggle value="italics">Italics</Toggle>
  <Toggle value="underline">Underline</Toggle>
</ToggleGroup>

Controlled

When controlled, pass the value and onValueChange props to ToggleGroup:

const [value, setValue] = React.useState(['align-center']);

return (
  <ToggleGroup value={value} onValueChange={setValue}>
    <Toggle value="align-left" />
    <Toggle value="align-center" />
    <Toggle value="align-right" />
  </ToggleGroup>
);

Customization

Orientation

Use the orientation prop to configure a vertical toggle group:

<ToggleGroup orientation="vertical">{/* Toggles */}</ToggleGroup>

Allow multiple buttons to be pressed

Use the toggleMultiple prop to allow multiple buttons to be pressed at the same time:

<ToggleGroup toggleMultiple>
  <Toggle value="bold" />
  <Toggle value="italics" />
  <Toggle value="underline" />
</ToggleGroup>

'use client';
import * as React from 'react';
import { ToggleGroup } from '@base-ui-components/react/toggle-group';
import { Toggle } from '@base-ui-components/react/toggle';
import classes from './styles.module.css';

export default function ToggleGroupToggleMultiple() {
  return (
    <ToggleGroup
      toggleMultiple
      aria-label="Text formatting"
      className={classes.root}
    >
      <Toggle value="bold" aria-label="Toggle bold" className={classes.button}>
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="24"
          height="24"
          viewBox="0 0 24 24"
          className={classes.icon}
        >
          <path d="M6 4h8a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
          <path d="M6 12h9a4 4 0 0 1 4 4 4 4 0 0 1-4 4H6z" />
        </svg>
      </Toggle>

      <Toggle value="italics" aria-label="Toggle italics" className={classes.button}>
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="24"
          height="24"
          viewBox="0 0 24 24"
          className={classes.icon}
        >
          <line x1="19" y1="4" x2="10" y2="4" />
          <line x1="14" y1="20" x2="5" y2="20" />
          <line x1="15" y1="4" x2="9" y2="20" />
        </svg>
      </Toggle>

      <Toggle
        value="underline"
        aria-label="Toggle underline"
        className={classes.button}
      >
        <svg
          xmlns="http://www.w3.org/2000/svg"
          width="24"
          height="24"
          viewBox="0 0 24 24"
          className={classes.icon}
        >
          <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
          <line x1="4" y1="21" x2="20" y2="21" />
        </svg>
      </Toggle>
    </ToggleGroup>
  );
}

One button must be pressed

Use controlled mode to always keep one button in the pressed state:

const [value, setValue] = React.useState(['align-left']);

const handleValueChange = (newValue) => {
  if (newValue.length > 0) {
    setValue(newValue);
  }
};

return (
  <ToggleGroup value={value} onValueChange={handleValueChange}>
    <Toggle value="align-left" />
    <Toggle value="align-center" />
    <Toggle value="align-right" />
  </ToggleGroup>
);

Accessibility

The ToggleGroup component, and every Toggle within must be given must be given an accessible name with aria-label or aria-labelledby.
The Toggle's label or accessible name must not change based on the pressed state to ensure a smooth screen-reader experience, otherwise it may duplicate the announcement of the pressed state based on aria-pressed.

API Reference

ToggleGroupRoot

Prop	Type	Default	Description
`className`	`union`		Class names applied to the element or a function that returns them based on the component's state.
`defaultValue`	`array`		The open state of the ToggleGroup represented by an array of the values of all pressed `<ToggleGroup.Item/>`s This is the uncontrolled counterpart of `value`.
`onValueChange`	`func`		Callback fired when the pressed states of the ToggleGroup changes.
`render`	`union`		A function to customize rendering of the component.
`toggleMultiple`	`bool`	`false`	When `false` only one item in the group can be pressed. If any item in the group becomes pressed, the others will become unpressed. When `true` multiple items can be pressed.
`value`	`array`		The open state of the ToggleGroup represented by an array of the values of all pressed `<ToggleGroup.Item/>`s This is the controlled counterpart of `defaultValue`.