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

defaultValue

any[]

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

value

any[]

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

onValueChange

function

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

toggleMultiple

boolean

(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

disabled

boolean

(default:

false

)

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

loop

boolean

(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

orientation

Orientation

(default:

'horizontal'

)

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

className

string | 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)

render

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