Toggle Group
newLike a button group, but they remember what you picked
Open Props in the corner of the example to try activeVariant, color, orientation and disabled.
Installation
Usage
<script setup lang="ts">
import { Bold, Italic, Underline } from '@lucide/vue'
import { ToggleGroup, ToggleGroupItem } from '@/components/ui/toggle-group'
const formatting = ref<string[]>([])
</script>
<template>
<ToggleGroup v-model="formatting" type="multiple" variant="outline" size="icon-md">
<ToggleGroupItem value="bold" aria-label="Bold"><Bold /></ToggleGroupItem>
<ToggleGroupItem value="italic" aria-label="Italic"><Italic /></ToggleGroupItem>
<ToggleGroupItem value="underline" aria-label="Underline"><Underline /></ToggleGroupItem>
</ToggleGroup>
</template>
ToggleGroup is Reka UI's toggle group laid out like a Button Group: the items join, with the inner corners squared and outlined edges shared. Tab reaches the group once, and the arrow keys move between its items. Each item is a Toggle and takes its variants, colours and sizes.
Examples
Single
type="single" keeps at most one item on and binds its value as a string; type="multiple" binds an array.
Style
variant, activeVariant, color, activeColor and size on the group apply to every item, and an item's own props override them.
API Reference
class is also accepted on every part and merged over its classes with tailwind-merge.
ToggleGroup
| Prop | Default | Type and description |
|---|---|---|
| rovingFocus | — | booleanTab reaches the group once and the arrow keys move between the items. On by default. |
| disabled | — | booleanDisables every item. |
| orientation | "horizontal" | DataOrientationThe direction the items run in, and the arrow keys that move between them. |
| dir | — | DirectionReading direction. Mirrors the arrow keys in |
| loop | — | booleanArrow keys wrap from the last item to the first and back. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| name | — | stringThe field name, for submitting the value with a form. |
| required | — | booleanMarks the form field as required. |
| type | — | SingleOrMultipleType
|
| modelValue | — | AcceptableValue | AcceptableValue[]The value of the item that is on, or an array of them with |
| defaultValue | — | AcceptableValue | AcceptableValue[]The value it starts with when |
| variant | "ghost" | "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullButton's variant for every item while it is off. |
| activeVariant | "soft" | "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullButton's variant for every item while it is on. |
| color | "neutral" | ButtonColor | (string & {})The colour of every item while it is off. |
| activeColor | — | ButtonColor | (string & {})The colour of every item while it is on. Follows |
| size | "md" | "md" | "xs" | "sm" | "lg" | "xl" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg" | "icon-xl" | nullButton's size for every item. |
| Event | Payload and description |
|---|---|
| update:modelValue | [payload: AcceptableValue | AcceptableValue[]]Fires when an item is pressed, with the new value. |
| Slot | Scope and description |
|---|---|
| default | { modelValue: AcceptableValue | AcceptableValue[] | undefined; }The items. Receives |
ToggleGroupItem
| Prop | Default | Type and description |
|---|---|---|
| value* | — | AcceptableValueThe value this item adds to the group's value when it is on. |
| disabled | — | booleanDisables this item. |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | "button" | AsTag | ComponentThe element or component to render. |
| variant | — | "solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullOverrides the group's |
| activeVariant | — | "solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullOverrides the group's |
| color | — | ButtonColor | (string & {})Overrides the group's |
| activeColor | — | ButtonColor | (string & {})Overrides the group's |
| size | — | "xs" | "sm" | "md" | "lg" | "xl" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg" | "icon-xl" | nullOverrides the group's |
| Slot | Scope and description |
|---|---|
| default | { modelValue: boolean; state: DataState; pressed: boolean; disabled: boolean; }The label and icons. Receives |
Props
- rovingFocus
booleanTab reaches the group once and the arrow keys move between the items. On by default.- disabled
booleanDisables every item.- orientation
"horizontal" DataOrientationThe direction the items run in, and the arrow keys that move between them.- dir
DirectionReading direction. Mirrors the arrow keys inrtl.- loop
booleanArrow keys wrap from the last item to the first and back.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- name
stringThe field name, for submitting the value with a form.- required
booleanMarks the form field as required.- type
SingleOrMultipleTypesinglekeeps at most one item on and binds a string;multiplebinds an array.- modelValue
AcceptableValue | AcceptableValue[]The value of the item that is on, or an array of them withtype="multiple", bound withv-model.- defaultValue
AcceptableValue | AcceptableValue[]The value it starts with whenv-modelis not used.- variant
"ghost" "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullButton's variant for every item while it is off.ghostby default.- activeVariant
"soft" "ghost" | "soft" | "solid" | "subtle" | "outline" | "link" | nullButton's variant for every item while it is on.softby default.- color
"neutral" ButtonColor | (string & {})The colour of every item while it is off.neutralby default.- activeColor
ButtonColor | (string & {})The colour of every item while it is on. Followscolorwhen not set.- size
"md" "md" | "xs" | "sm" | "lg" | "xl" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg" | "icon-xl" | nullButton's size for every item.
Emits
- update:modelValue
[payload: AcceptableValue | AcceptableValue[]]Fires when an item is pressed, with the new value.
Slots
- default
{ modelValue: AcceptableValue | AcceptableValue[] | undefined; }The items. ReceivesmodelValue.
Props
- value*
AcceptableValueThe value this item adds to the group's value when it is on.- disabled
booleanDisables this item.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
"button" AsTag | ComponentThe element or component to render.- variant
"solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullOverrides the group'svariant.- activeVariant
"solid" | "soft" | "subtle" | "outline" | "ghost" | "link" | nullOverrides the group'sactiveVariant.- color
ButtonColor | (string & {})Overrides the group'scolor.- activeColor
ButtonColor | (string & {})Overrides the group'sactiveColor.- size
"xs" | "sm" | "md" | "lg" | "xl" | "icon-xs" | "icon-sm" | "icon-md" | "icon-lg" | "icon-xl" | nullOverrides the group'ssize.
Slots
- default
{ modelValue: boolean; state: DataState; pressed: boolean; disabled: boolean; }The label and icons. ReceivesmodelValue,pressed,stateanddisabled.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| toggle-group | data-orientation, data-size | The group, with role="group". |
| toggle-group-item | data-state, data-variant, data-color, data-active-color, data-size, data-disabled | One toggle. data-state is on or off. |