ToggleGroup

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

<script setup lang="ts">
import { ToggleGroupItem, ToggleGroupRoot } from 'radix-vue'
import { Icon } from '@iconify/vue'
import { ref } from 'vue'

const toggleStateSingle = ref('left')
const toggleStateMultiple = ref(['italic'])

const toggleGroupItemClasses
  = 'hover:bg-green3 text-mauve11 data-[state=on]:bg-green6 data-[state=on]:text-violet12 flex h-[35px] w-[35px] items-center justify-center bg-white text-base leading-4 first:rounded-l last:rounded-r focus:z-10 focus:shadow-[0_0_0_2px] focus:shadow-black focus:outline-none'
</script>

<template>
  <div>
    <ToggleGroupRoot v-model="toggleStateSingle" class="flex">
      <ToggleGroupItem value="left" aria-label="Toggle italic" :class="toggleGroupItemClasses">
        <Icon icon="radix-icons:text-align-left" class="w-[15px] h-[15px]" />
      </ToggleGroupItem>
      <ToggleGroupItem value="center" aria-label="Toggle italic" :class="toggleGroupItemClasses">
        <Icon icon="radix-icons:text-align-center" class="w-[15px] h-[15px]" />
      </ToggleGroupItem>
      <ToggleGroupItem value="right" aria-label="Toggle italic" :class="toggleGroupItemClasses">
        <Icon icon="radix-icons:text-align-right" class="w-[15px] h-[15px]" />
      </ToggleGroupItem>
    </ToggleGroupRoot>
    <br>
    <ToggleGroupRoot v-model="toggleStateMultiple" type="multiple" class="flex">
      <ToggleGroupItem value="bold" aria-label="Toggle italic" :class="toggleGroupItemClasses">
        <Icon icon="radix-icons:font-bold" class="w-[15px] h-[15px]" />
      </ToggleGroupItem>
      <ToggleGroupItem value="italic" aria-label="Toggle italic" :class="toggleGroupItemClasses">
        <Icon icon="radix-icons:font-italic" class="w-[15px] h-[15px]" />
      </ToggleGroupItem>
      <ToggleGroupItem value="strikethrough" aria-label="Toggle italic" :class="toggleGroupItemClasses">
        <Icon icon="radix-icons:strikethrough" class="w-[15px] h-[15px]" />
      </ToggleGroupItem>
    </ToggleGroupRoot>
  </div>
</template>

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 install radix-vue

Anatomy

Import the component.

<script setup>
import { ToggleGroupItem, ToggleGroupRoot } from 'radix-vue'
</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 overwrite 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		string | string[] 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 DirectionProvider 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		string | string[] 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
orientation		'vertical' | 'horizontal' The orientation of the component, which determines how focus moves: horizontal for left/right arrows and vertical for up/down arrows.
rovingFocus	true	boolean When false, navigating through the items using arrow keys will be disabled.
type	'single'	'single' | 'multiple' Determines whether a "single" or "multiple" items can be pressed at a time. This prop will be ignored if any of v-model or defaultValue is an defined, as the type will be inferred from the value.

Emit	Payload
update:modelValue	[payload: string] Event handler called when the value changes.

Slots (default)	Payload
modelValue	string | string[] | 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 overwrite 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.
pressed		boolean The controlled pressed state of the toggle. Can be bind as v-model.
value*		string 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.

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

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

<template>
  <ToggleGroupRoot v-model="value" type="single">
    <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.