ToggleGroup
ToggleGroup provides a set of two-state buttons that can either be off (not pressed) or on (pressed).
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 oftoggles<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>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>
);RTL
To change direction for right-to-left languages, place the component in DirectionProvider with the direction="rtl" prop to configure RTL behavior, and set the dir attribute accordingly in your HTML to affect styling:
<html dir="rtl">
<body>
<DirectionProvider direction="rtl">
<ToggleGroup>{/* Subcomponents */}</ToggleGroup>
</DirectionProvider>
</body>
</html>When RTL, the behavior of the left and right arrow keys are reversed - Left Arrow moves focus to the next toggle and Right Arrow moves focus to the previous toggle.
Accessibility
- The
ToggleGroupcomponent, and everyTogglewithin must be given must be given an accessible name witharia-labeloraria-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 onaria-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. |