Ark Logo

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:

<script setup lang="ts">
import { ToggleGroup } from '@ark-ui/vue'
</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.

<script setup lang="ts">
import { ToggleGroup } from '@ark-ui/vue'
</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.

<script setup lang="ts">
import { ref } from 'vue'
import { ToggleGroup } from '@ark-ui/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>

API Reference

Root

PropDefaultType
asChildfalse
boolean

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.

modelValue
string[]

multiple
boolean

Whether to allow multiple toggles to be selected.

orientation'horizontal'
Orientation

The orientation of the toggle group.

rovingFocustrue
boolean

Whether to use roving tab index to manage focus.

EmitEvent
update:modelValue
[value: string[]]

The callback fired when the model value changes.

valueChange
[details: ValueChangeDetails]

Function to call when the toggle is clicked.

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

asChildfalse
boolean

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"

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.