Skip to main content

​
Overview

Toggle Group provides a set of toggle buttons that work together. It supports both single and multiple selection modes, making it useful for toolbar buttons, formatting options, or filter selections.

​
Features

  • Supports single or multiple selection
  • Can be controlled or uncontrolled
  • Full keyboard navigation with roving focus
  • Supports horizontal/vertical orientation
  • Accessible by default with proper ARIA attributes

​
Installation

npm install @radix-ui/react-toggle-group

​
Anatomy

import * as ToggleGroup from '@radix-ui/react-toggle-group';

export default () => (
  <ToggleGroup.Root>
    <ToggleGroup.Item />
  </ToggleGroup.Root>
);

​
API Reference

​
Root

Contains all the toggle group items.
​
type
'single' | 'multiple'
required
Determines whether a single or multiple items can be pressed at a time.
When type="single":
​
value
string
The controlled value of the pressed item.
​
defaultValue
string
The value of the item to show as pressed when initially rendered (uncontrolled).
​
onValueChange
(value: string) => void
Event handler called when the pressed state changes.
When type="multiple":
​
value
string[]
The controlled value of the pressed items.
​
defaultValue
string[]
The values of the items to show as pressed when initially rendered (uncontrolled).
​
onValueChange
(value: string[]) => void
Event handler called when the pressed state changes.
Common props:
​
disabled
boolean
When true, prevents the user from interacting with the toggle group and all its items.
​
rovingFocus
boolean
default:"true"
When false, navigating through the items using arrow keys will be disabled.
​
orientation
'horizontal' | 'vertical'
default:"'horizontal'"
The orientation of the component.
​
dir
'ltr' | 'rtl'
The reading direction of the toggle group. If omitted, inherits from the parent.
​
loop
boolean
default:"true"
When loop and rovingFocus are true, keyboard navigation will loop from last item to first, and vice versa.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child.

​
Item

An item in the toggle group.
​
value
string
required
A unique value for the item.
​
disabled
boolean
When true, prevents the user from interacting with the item.
​
asChild
boolean
default:"false"
Change the default rendered element for the one passed as a child.

​
Example

import * as ToggleGroup from '@radix-ui/react-toggle-group';
import {
  TextAlignLeftIcon,
  TextAlignCenterIcon,
  TextAlignRightIcon,
} from '@radix-ui/react-icons';
import './styles.css';

export default () => (
  <ToggleGroup.Root
    className="ToggleGroup"
    type="single"
    defaultValue="center"
    aria-label="Text alignment"
  >
    <ToggleGroup.Item className="ToggleGroupItem" value="left" aria-label="Left aligned">
      <TextAlignLeftIcon />
    </ToggleGroup.Item>
    <ToggleGroup.Item className="ToggleGroupItem" value="center" aria-label="Center aligned">
      <TextAlignCenterIcon />
    </ToggleGroup.Item>
    <ToggleGroup.Item className="ToggleGroupItem" value="right" aria-label="Right aligned">
      <TextAlignRightIcon />
    </ToggleGroup.Item>
  </ToggleGroup.Root>
);

​
Accessibility

Uses roving tabindex to manage focus movement among items.

​
Keyboard Interactions

  • Tab - Moves focus to either the pressed item or the first item in the group.
  • Space - Activates/deactivates the item.
  • Enter - Activates/deactivates the item.
  • ArrowDown - Moves focus to the next item in the group (vertical orientation).
  • ArrowRight - Moves focus to the next item in the group (horizontal orientation).
  • ArrowUp - Moves focus to the previous item in the group (vertical orientation).
  • ArrowLeft - Moves focus to the previous item in the group (horizontal orientation).
  • Home - Moves focus to the first item.
  • End - Moves focus to the last item.

​
Data Attributes

Root
  • [data-orientation] - “horizontal” or “vertical”
Item
  • [data-state] - “on” or “off”
  • [data-disabled] - Present when disabled
  • [data-orientation] - “horizontal” or “vertical”

Build docs developers (and LLMs) love

Get started for freeTalk to us