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

import { ToggleGroup } from '@ark-ui/solid/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>
  )
}

<script setup lang="ts">
import { ToggleGroup } from '@ark-ui/vue/toggle-group'
</script>

<template>
  <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>
</template>

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

import { ToggleGroup } from '@ark-ui/solid/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>
  )
}

<script setup lang="ts">
import { ToggleGroup } from '@ark-ui/vue/toggle-group'
</script>

<template>
  <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>
</template>

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

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

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

<script setup lang="ts">
import { ToggleGroup } from '@ark-ui/vue/toggle-group'
import { ref } from 'vue'

const value = ref(['b'])
</script>

<template>
  <ToggleGroup.Root v-model="value">
    <ToggleGroup.Item value="a">A</ToggleGroup.Item>
    <ToggleGroup.Item value="b">B</ToggleGroup.Item>
    <ToggleGroup.Item value="c">C</ToggleGroup.Item>
  </ToggleGroup.Root>
</template>

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>
    </>
  )
}

import { ToggleGroup, useToggleGroup } from '@ark-ui/solid/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>
    </>
  )
}

<script setup lang="ts">
import { ToggleGroup, useToggleGroup } from '@ark-ui/vue/toggle-group'

const toggleGroup = useToggleGroup()
</script>

<template>
  <button @click="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>
</template>

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

API Reference

Root

Prop	Default	Type
`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.
`loopFocus`	`true`	`boolean` Whether to loop focus inside the toggle group.
`modelValue`		`string[]`
`multiple`		`boolean` Whether to allow multiple toggles to be selected.
`orientation`	`'horizontal'`	`Orientation` The orientation of the toggle group.
`rovingFocus`	`true`	`boolean` Whether to use roving tab index to manage focus.

Emit	Event
`update:modelValue`	`[value: string[]]` The callback fired when the model value changes.
`valueChange`	`[details: ValueChangeDetails]` Function to call when the toggle is clicked.

Data Attribute	Value
`[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

Prop	Default	Type
`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 Attribute	Value
`[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

Prop	Default	Type
`value`		`MachineApi<PropTypes>`
`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

Key	Description
`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.