Toggle Group

Provides a shared state to a series of toggle buttons.

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

export default function ExampleToggleGroup() {
  return (
    <ToggleGroup defaultValue={['left']} className={styles.Panel}>
      <Toggle aria-label="Align left" value="left" className={styles.Button}>
        <AlignLeftIcon className={styles.Icon} />
      </Toggle>
      <Toggle aria-label="Align center" value="center" className={styles.Button}>
        <AlignCenterIcon className={styles.Icon} />
      </Toggle>
      <Toggle aria-label="Align right" value="right" className={styles.Button}>
        <AlignRightIcon className={styles.Icon} />
      </Toggle>
    </ToggleGroup>
  );
}

function AlignLeftIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="16"
      height="16"
      viewBox="0 0 16 16"
      stroke="currentcolor"
      strokeLinecap="round"
      {...props}
    >
      <path d="M2.5 3.5H13.5" />
      <path d="M2.5 9.5H13.5" />
      <path d="M2.5 6.5H10.5" />
      <path d="M2.5 12.5H10.5" />
    </svg>
  );
}

function AlignCenterIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="16"
      height="16"
      viewBox="0 0 16 16"
      stroke="currentcolor"
      strokeLinecap="round"
      {...props}
    >
      <path d="M3 3.5H14" />
      <path d="M3 9.5H14" />
      <path d="M4.5 6.5H12.5" />
      <path d="M4.5 12.5H12.5" />
    </svg>
  );
}

function AlignRightIcon(props: React.ComponentProps<'svg'>) {
  return (
    <svg
      width="16"
      height="16"
      viewBox="0 0 16 16"
      stroke="currentcolor"
      strokeLinecap="round"
      {...props}
    >
      <path d="M2.5 3.5H13.5" />
      <path d="M2.5 9.5H13.5" />
      <path d="M5.5 6.5H13.5" />
      <path d="M5.5 12.5H13.5" />
    </svg>
  );
}

Anatomy

Import the component and use it as a single part:

Anatomy

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

<ToggleGroup />

API reference

defaultValueany[]

Name: defaultValue
Description: The open state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the uncontrolled counterpart of value.
Type: any[] | undefined

valueany[]

Name: value
Description: The open state of the toggle group represented by an array of the values of all pressed toggle buttons. This is the controlled counterpart of defaultValue.
Type: any[] | undefined

onValueChangefunction

Name: onValueChange
Description: Callback fired when the pressed states of the toggle group changes.
Type: | (( groupValue: any[], eventDetails: Toggle.Group.ChangeEventDetails, ) => void) | undefined

toggleMultipleboolean(default: false)

Name: toggleMultiple
Description: 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.
Type: boolean | undefined
Default: false

disabledboolean(default: false)

Name: disabled
Description: Whether the toggle group should ignore user interaction.
Type: boolean | undefined
Default: false

loopboolean(default: true)

Name: loop
Description: Whether to loop keyboard focus back to the first item when the end of the list is reached while using the arrow keys.
Type: boolean | undefined
Default: true

orientationOrientation(default: 'horizontal')

Name: orientation
Type: 'horizontal' | 'vertical' | undefined
Default: 'horizontal'

classNamestring | function

Name: className
Description: CSS class applied to the element, or a function that returns a class based on the component’s state.
Type: string | ((state: Toggle.Group.State) => string)

renderReactElement | function

Name: render
Description: Allows you to replace the component’s HTML element with a different tag, or compose it with another component.

Accepts a ReactElement or a function that returns the element to render.
Type: | ReactElement | (( props: HTMLProps, state: Toggle.Group.State, ) => ReactElement)

data-orientation

Indicates the orientation of the toggle group.

data-disabled

Present when the toggle group is disabled.

data-multiple

Present when the toggle group allows multiple buttons to be in the pressed state at the same time.

Attribute	Description
`data-orientation`	Indicates the orientation of the toggle group.
`data-disabled`	Present when the toggle group is disabled.
`data-multiple`	Present when the toggle group allows multiple buttons to be in the pressed state at the same time.