Components
Toggle group

Toggle Group

A set of two-state buttons that can be toggled on or off.

Anatomy

To set up the toggle group correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Examples

Learn how to use the ToggleGroup component in your project. Let's take a look at the most basic example:

import { ToggleGroup } from '@ark-ui/react/toggle-group'

export const Basic = () => {
  return (
    <ToggleGroup.Root>
      <ToggleGroup.Item value="a">A</ToggleGroup.Item>
      <ToggleGroup.Item value="b">B</ToggleGroup.Item>
      <ToggleGroup.Item value="c">C</ToggleGroup.Item>
    </ToggleGroup.Root>
  )
}

Multiple Selection

Demonstrates how to enable multiple selection within the group.

import { ToggleGroup } from '@ark-ui/react/toggle-group'

export const Multiple = () => {
  return (
    <ToggleGroup.Root multiple>
      <ToggleGroup.Item value="a">A</ToggleGroup.Item>
      <ToggleGroup.Item value="b">B</ToggleGroup.Item>
      <ToggleGroup.Item value="c">C</ToggleGroup.Item>
    </ToggleGroup.Root>
  )
}

Initial Value

Shows how to set an initial value in the toggle group.

import { ToggleGroup } from '@ark-ui/react/toggle-group'

export const InitialValue = () => {
  return (
    <ToggleGroup.Root defaultValue={['b']}>
      <ToggleGroup.Item value="a">A</ToggleGroup.Item>
      <ToggleGroup.Item value="b">B</ToggleGroup.Item>
      <ToggleGroup.Item value="c">C</ToggleGroup.Item>
    </ToggleGroup.Root>
  )
}

Using the Root Provider

The RootProvider component provides a context for the toggle-group. It accepts the value of the useToggle-group hook. You can leverage it to access the component state and methods from outside the toggle-group.

import { ToggleGroup, useToggleGroup } from '@ark-ui/react/toggle-group'

export const RootProvider = () => {
  const toggleGroup = useToggleGroup()

  return (
    <>
      <button onClick={() => toggleGroup.setValue(['b'])}>Set to B</button>

      <ToggleGroup.RootProvider value={toggleGroup}>
        <ToggleGroup.Item value="a">A</ToggleGroup.Item>
        <ToggleGroup.Item value="b">B</ToggleGroup.Item>
        <ToggleGroup.Item value="c">C</ToggleGroup.Item>
      </ToggleGroup.RootProvider>
    </>
  )
}

If you're using the RootProvider component, you don't need to use the Root component.

API Reference

Root

PropDefaultType
asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
defaultValue
string[]

The initial value of the toggle group when it is first rendered. Use when you do not need to control the state of the toggle group.

disabled
boolean

Whether the toggle is disabled.

id
string

The unique identifier of the machine.

ids
Partial<{ root: string; item(value: string): string }>

The ids of the elements in the toggle. Useful for composition.

loopFocustrue
boolean

Whether to loop focus inside the toggle group.

multiple
boolean

Whether to allow multiple toggles to be selected.

onValueChange
(details: ValueChangeDetails) => void

Function to call when the toggle is clicked.

orientation'horizontal'
Orientation

The orientation of the toggle group.

rovingFocustrue
boolean

Whether to use roving tab index to manage focus.

value
string[]

The values of the toggles in the group.

Data AttributeValue
[data-scope]toggle-group
[data-part]root
[data-disabled]Present when disabled
[data-orientation]The orientation of the toggle-group
[data-focus]Present when focused

Item

PropDefaultType
value
string

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.
disabled
boolean

Data AttributeValue
[data-scope]toggle-group
[data-part]item
[data-focus]Present when focused
[data-disabled]Present when disabled
[data-orientation]The orientation of the item
[data-state]"on" | "off"

RootProvider

PropDefaultType
value
UseToggleGroupReturn

asChild
boolean

Use the provided child element as the default rendered element, combining their props and behavior.

For more details, read our Composition guide.

Accessibility

Keyboard Support

KeyDescription
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.
ArrowRight
Moves focus to the next item in the group.
ArrowUp
Moves focus to the previous item in the group.
ArrowLeft
Moves focus to the previous item in the group.
Home
Moves focus to the first item.
End
Moves focus to the last item.