ToggleGroup

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

View code

Features

Full keyboard navigation.
Supports horizontal/vertical orientation.
Support single and multiple pressed buttons.
Can be controlled or uncontrolled.

Installation

Install the component from your command line.

$ npm add reka-ui

Anatomy

Import the component.

vue

<script setup>
import { ToggleGroupItem, ToggleGroupRoot } from 'reka-ui'
</script>

<template>
  <ToggleGroupRoot>
    <ToggleGroupItem />
  </ToggleGroupRoot>
</template>

API Reference

Root

Contains all the parts of a toggle group.

Prop	Default	Type
`as`	`'div'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`defaultValue`		`AcceptableValue \| AcceptableValue[]` The default active value of the item(s). Use when you do not need to control the state of the item(s).
`dir`		`'ltr' \| 'rtl'` The reading direction of the combobox when applicable. If omitted, inherits globally from `ConfigProvider` or assumes LTR (left-to-right) reading mode.
`disabled`	`false`	`boolean` When `true`, prevents the user from interacting with the toggle group and all its items.
`loop`	`true`	`boolean` When `loop` and `rovingFocus` is `true`, keyboard navigation will loop from last item to first, and vice versa.
`modelValue`		`AcceptableValue \| AcceptableValue[]` The controlled value of the active item(s). Use this when you need to control the state of the items. Can be binded with `v-model`
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`orientation`		`'vertical' \| 'horizontal'` The orientation of the component, which determines how focus moves: `horizontal` for left/right arrows and `vertical` for up/down arrows.
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`rovingFocus`	`true`	`boolean` When `false`, navigating through the items using arrow keys will be disabled.
`type`		`'single' \| 'multiple'` Determines whether a "single" or "multiple" items can be selected at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`.

Emit	Payload
`update:modelValue`	`[payload: AcceptableValue \| AcceptableValue[]]` Event handler called when the value of the toggle changes.

Slots (default)	Payload
`modelValue`	`AcceptableValue \| AcceptableValue[] \| undefined` Current toggle values

Data Attribute	Value
`[data-orientation]`	`"vertical" \| "horizontal"`

Item

An item in the group.

Prop	Default	Type
`as`	`'button'`	`AsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`defaultValue`		`boolean` The pressed state of the toggle when it is initially rendered. Use when you do not need to control its open state.
`disabled`		`boolean` When `true`, prevents the user from interacting with the toggle.
`modelValue`		`boolean \| null` The controlled pressed state of the toggle. Can be bind as `v-model`.
`value*`		`AcceptableValue` A string value for the toggle group item. All items within a toggle group should use a unique value.

Data Attribute	Value
`[data-state]`	`"on" \| "off"`
`[data-disabled]`	Present when disabled
`[data-orientation]`	`"vertical" \| "horizontal"`

Examples

Ensuring there is always a value

You can control the component to ensure a value.

vue

<script setup>
import { ref } from 'vue'
import { ToggleGroupItem, ToggleGroupRoot } from 'reka-ui'

const value = ref('left')
</script>

<template>
  <ToggleGroupRoot
    :model-value="value"
    @update:model-value="(val) => {
      if (val) value = val
    }"
  >
    <ToggleGroupItem value="left">
      <TextAlignLeftIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="center">
      <TextAlignCenterIcon />
    </ToggleGroupItem>
    <ToggleGroupItem value="right">
      <TextAlignRightIcon />
    </ToggleGroupItem>
  </ToggleGroupRoot>
</template>

Accessibility

Uses roving tabindex to manage focus movement among items.

Keyboard Interactions

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.

ToggleGroup ​

Features ​

Installation ​

Anatomy ​

API Reference ​

Root ​

Item ​

Examples ​

Ensuring there is always a value ​

Accessibility ​

Keyboard Interactions ​