Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Actions

ToggleGroup

Coordinates a roving set of single- or multiple-selection toggle buttons.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add toggle-group

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import ToggleGroup from './components/ui/toggle-group/ToggleGroup.vue'
import ToggleGroupItem from './components/ui/toggle-group/ToggleGroupItem.vue'

const alignment = ref<string>()
</script>

<template>
  <ToggleGroup v-model="alignment" aria-label="Text alignment">
    <ToggleGroupItem value="left">Left</ToggleGroupItem>
    <ToggleGroupItem value="center">Center</ToggleGroupItem>
    <ToggleGroupItem value="right">Right</ToggleGroupItem>
  </ToggleGroup>
</template>

Name the root with aria-label or aria-labelledby. Arrow keys follow orientation and text direction, Home and End move to the edges, and disabled items are skipped.

When to use it

One-of-many view

Use single mode for mutually exclusive display choices.

Multiple filters

Use multiple mode when several options can be active together.

More examples

Choose density

Single mode stores one selected value.

Choose density
<script setup lang="ts">
import { ref } from 'vue'
import ToggleGroup from './components/ui/toggle-group/ToggleGroup.vue'
import ToggleGroupItem from './components/ui/toggle-group/ToggleGroupItem.vue'

const density = ref<string>()
</script>
<template>
  <ToggleGroup v-model="density" type="single" aria-label="List density">
    <ToggleGroupItem value="compact">Compact</ToggleGroupItem>
    <ToggleGroupItem value="comfortable">Comfortable</ToggleGroupItem>
  </ToggleGroup>
</template>

Select visible layers

Multiple mode stores an array of active values.

Select visible layers
<script setup lang="ts">
import { ref } from 'vue'
import ToggleGroup from './components/ui/toggle-group/ToggleGroup.vue'
import ToggleGroupItem from './components/ui/toggle-group/ToggleGroupItem.vue'

const layers = ref<string[]>(['roads'])
</script>
<template>
  <ToggleGroup v-model="layers" type="multiple" aria-label="Map layers">
    <ToggleGroupItem value="roads">Roads</ToggleGroupItem>
    <ToggleGroupItem value="transit">Transit</ToggleGroupItem>
    <ToggleGroupItem value="terrain">Terrain</ToggleGroupItem>
  </ToggleGroup>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

ToggleGroup

Complete API for ToggleGroup
NameType or signatureDefaultWhat it does
typeprop"single" | "multiple" | undefined"single"Choose the native HTML control type or action behavior.
orientationprop"horizontal" | "vertical" | undefined"horizontal"Arrange items horizontally or vertically.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
looppropboolean | undefinedtrueWrap keyboard navigation from the last item to the first.
modelValuemodelToggleGroupValueundefinedCurrent value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: ToggleGroupValue]—Requests a new model value from the parent.
defaultslot() => unknownRequiredContent shown inside ToggleGroup.

ToggleGroupItem

Complete API for ToggleGroupItem
NameType or signatureDefaultWhat it does
valuepropstringRequiredValue represented by this control or option.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
defaultslot(props: { pressed: boolean; }) => unknownRequiredContent shown inside ToggleGroupItem.
elementexposedHTMLButtonElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
Public type definitions
Public types
// packages/frameworks/vue/components/toggle-group/types.ts
// ------- TYPES -------

export type ToggleGroupValue = string | string[] | undefined

export interface ToggleGroupProps {
  type?: 'single' | 'multiple'
  orientation?: 'horizontal' | 'vertical'
  disabled?: boolean
  loop?: boolean
}

export interface ToggleGroupItemProps {
  value: string
  disabled?: boolean
}

Implementation notes

  • Each item requires a unique string value.
  • Horizontal groups scroll within the available width when their buttons need more room.
  • Arrow keys move the roving focus; Home and End jump to the first and last enabled item.
  • Enabled items shape their label on hover and press while keeping the button bounds fixed; hover does not change selection, and reduced-motion settings keep the feedback still.
  • In single mode, the selected background stretches as it travels between items, then settles. Server-rendered selection stays visible until its first measurement, and reduced-motion preferences disable the slide. Multiple mode keeps separate backgrounds on selected items.

Accessibility and localization

  • Name the root with aria-label or aria-labelledby.
  • Arrow direction follows orientation and text direction, including RTL.

Source contract and editing guidance