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

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.