Toggle

A headless toggle button with dual-mode support: standalone boolean binding or group selection with single and multi-select.

Copy Markdown

PreviewRenders elementIntermediate Jun 29, 2026

Usage

The Toggle component supports two modes:

Standalone mode: Use v-model on Toggle.Root for simple boolean on/off state
Group mode: Wrap in Toggle.Group for single or multi-select with value-based selection

<script setup lang="ts">
  import { Toggle } from '@vuetify/v0'
  import { shallowRef } from 'vue'

  const saved = shallowRef(false)
</script>

<template>
  <div class="flex justify-center">
    <Toggle.Root
      v-model="saved"
      class="inline-flex items-center gap-2 px-4 py-2 rounded-lg border border-divider font-medium data-[state=on]:bg-primary data-[state=on]:text-on-primary data-[state=on]:border-primary"
    >
      <svg
        class="size-5 data-[state=off]:opacity-40"
        :data-state="saved ? 'on' : 'off'"
        stroke="currentColor"
        stroke-width="2"
        viewBox="0 0 24 24"
      >
        <path
          d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"
          :fill="saved ? 'currentColor' : 'none'"
        />
      </svg>

      Bookmark
    </Toggle.Root>
  </div>
</template>

Anatomy

vue

<script setup lang="ts">
  import { Toggle } from '@vuetify/v0'
</script>

<template>
  <Toggle.Root>
    <Toggle.Indicator />
  </Toggle.Root>

  <Toggle.Group>
    <Toggle.Root />
  </Toggle.Group>
</template>

This editor toolbar combines both group modes in one surface. The bold/italic/underline marks use a Toggle.Group with multiple, so any combination can be active at once and its v-model is an array of pressed values. Text alignment uses a second Toggle.Group without multiple but with mandatory, so exactly one of left/center/right is always selected and its v-model is a single string. A live preview paragraph reflects every choice in real time.

Internally multiple switches the group to createGroup (array model) while the plain group uses createSingle (single model); mandatory makes clicking the active alignment a no-op instead of clearing it, so the preview is never left unaligned. Each Toggle.Root carries a value selection key, and its pressed state surfaces as data-state="on" — the styling here is pure CSS via the data-[state=on]: variant, no slot props required. The composable owns the marks array and align string plus the tool metadata, the reusable component renders the two groups, and the entry composes the preview and a clear action.

Reach for multiple when choices are independent and additive, and for mandatory single-select when an unselected state is meaningless. Toggle is UI state, not form data — it has no name prop and no hidden input, so for values you intend to submit use Checkbox instead.

File	Role
`useEditorFormat.ts`	Owns the marks/align state, tool metadata, and derived preview classes and summary
`FormatToolbar.vue`	Renders the multiple marks group and the mandatory alignment group
`format-toolbar.vue`	Wires the composable to the toolbar and renders the live preview

The quick brown fox jumps over the lazy dog. Toggle the marks above to restyle this preview in real time.

Marks: Bold · Aligned left

Accessibility

Toggle renders as a native <button> element with proper ARIA attributes:

Attribute	Value	Description
`aria-pressed`	`true` / `false`	Reflects the pressed state
`aria-disabled`	`true` / absent	Present when disabled

Group ARIA

Attribute	Value	Description
`role`	`group`	Identifies the toggle group
`aria-orientation`	`horizontal` / `vertical`	Layout direction
`aria-disabled`	`true` / absent	Present when group is disabled

Keyboard

Key	Action
`Space`	Toggle pressed state
`Enter`	Toggle pressed state (native button behavior)

Data Attributes

Attribute	Values	Description
`data-state`	`on` / `off`	CSS styling hook for pressed state
`data-disabled`	present / absent	CSS styling hook for disabled state
`data-orientation`	`horizontal` / `vertical`	Group orientation (on group element)

FAQ

Discord

Need help? Join our community for support and discussions ↗

API Reference

The following API details are for all variations of the Toggle component.

Toggle.Root

6 props, 1 event, 1 slot

Toggle.Group

6 props, 1 event, 1 slot

Toggle.Indicator

1 prop, 1 slot