Toggle Group

Provides a shared state to a series of toggle buttons.

import * as React from 'react';
import { Toggle } from '@base-ui/react/toggle';
import { ToggleGroup } from '@base-ui/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/react/toggle-group';

<ToggleGroup />

API reference

defaultValue

string[]

—

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: string[] | undefined

value

string[]

—

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: string[] | undefined

onValueChange

function

—

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

loopFocus

boolean

true

Name: loopFocus
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

multiple

boolean

false

Name: multiple
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

false

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

orientation

Orientation

'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: ToggleGroup.State) => string | undefined) | undefined

style

React.CSSProperties | function

—

Name: style
Type: | React.CSSProperties | (( state: ToggleGroup.State, ) => React.CSSProperties | undefined) | undefined

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: ToggleGroup.State, ) => ReactElement) | undefined

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.

Additional Types

ToggleGroup.Props

Re-Export of ToggleGroup props as ToggleGroupProps

ToggleGroup.State

type ToggleGroupState = {
  disabled: boolean;
  multiple: boolean;
  orientation: 'horizontal' | 'vertical';
}

ToggleGroup.ChangeEventReason

type ToggleGroupChangeEventReason = 'none';

ToggleGroup.ChangeEventDetails

type ToggleGroupChangeEventDetails = {
  reason: 'none';
  event: Event;
  cancel: () => void;
  allowPropagation: () => void;
  isCanceled: boolean;
  isPropagationAllowed: boolean;
  trigger: Element | undefined;
};