Components

Toggle Group

Single or multiple pressed values with roving keyboard focus.

ToggleGroup manages a set of pressed buttons. It supports single or multiple selection, roving focus, form hidden values, item slots, and cancelable changes.

Use it for segmented controls, toolbars, and mutually exclusive or multi-select button groups. Use Checkbox Group when the choices are form-like checkboxes with labels and descriptions.

Anatomy

#item: Content inside each generated toggle button.

The group, hidden inputs, and buttons are generated by the component. The component owns aria-pressed, roving focus, and keyboard behavior; use ui.item for button styling.

<template>
  <ToggleGroup
    v-model="alignment"
    :allow-empty="false"
    :options="[
      { value: 'left', label: 'Left' },
      { value: 'center', label: 'Center' },
      { value: 'right', label: 'Right' },
    ]"
  />
</template>

Multiple selection

Use type="multiple" and bind to string[].

<template>
  <ToggleGroup
    v-model="formats"
    type="multiple"
    :options="[
      { value: 'bold', label: 'Bold' },
      { value: 'italic', label: 'Italic' },
      { value: 'underline', label: 'Underline' },
    ]"
  />
</template>

Card-style options

Use labels and descriptions for richer option cards.

<template>
  <ToggleGroup v-model="plan" :options="plans" :ui="{ root: 'grid gap-2' }">
    <template #item="{ label, description }">
      <span>
        <strong>{{ label }}</strong>
        <small>{{ description }}</small>
      </span>
    </template>
  </ToggleGroup>
</template>

Vertical orientation

Arrow key direction follows orientation.

<template>
  <ToggleGroup v-model="view" orientation="vertical" :options="views" />
</template>

Form values

When name is provided, selected values are submitted with the form. Multiple mode renders one hidden input per selected value.

<template>
  <ToggleGroup v-model="filters" type="multiple" name="filters" :options="options" />
</template>

API Reference

Props

Prop	Type	Default	Description
`options`	`ToggleGroupOption[]`	required	Toggle items.
`type`	`"single" \| "multiple"`	`"single"`	Selection mode.
`valueKey`	`string`	—	Object key used as item value. Falls back to `value`, then `label`.
`labelKey`	`string`	`"label"`	Object key used as item label.
`descriptionKey`	`string`	`"description"`	Object key used as item description.
`disabledKey`	`string`	`"disabled"`	Object key used as item disabled state.
`disabled`	`boolean`	`false`	Disabled state for the whole group.
`required`	`boolean`	`false`	Prevents clearing the last selected value.
`name`	`string`	—	Hidden form input name. Multiple mode renders one hidden input per selected value.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Roving focus direction.
`loop`	`boolean`	`true`	Arrow navigation wraps.
`rovingFocus`	`boolean`	`true`	Enables arrow-key roving focus.
`allowEmpty`	`boolean`	`true`	Allows single mode to clear selected item.
`ariaLabel`	`string`	—	Accessible group label.
`ariaLabelledby`	`string`	—	Accessible group label id.
`ui`	`ToggleGroupUi`	—	Classes for structural parts.

Emits

Event	Payload	Description
`value-change`	`(value, details)`	Fired before model updates. `details.cancel()` prevents the update.

Slots

Slot	Props	Description
`item`	`option`, `value`, `label`, `description`, `isPressed`, `isDisabled`, `select`	Custom item content.

UI Options

Key	Description
`root`	Root group.
`input`	Hidden form inputs.
`item`	Toggle button.
`label`	Default item label.
`description`	Default item description.

Styling Hooks

UI key	CSS class	Data attrs
`root`	`akaza-toggle-group`	`data-akaza-orientation`, `data-akaza-type`, `data-akaza-disabled`
`input`	`akaza-toggle-group-input`	—
`item`	`akaza-toggle-group-item`	`data-akaza-state`, `data-akaza-disabled`
`label`	`akaza-toggle-group-label`	—
`description`	`akaza-toggle-group-description`	—

Plain class applies to the root group.

Keyboard

Key	Behavior
`Enter` / `Space`	Toggle focused item.
Arrow keys	Move focus by orientation.
`Home` / `End`	Move focus to first/last enabled item.

Toggle

A two-state button that can be on or off.

Toolbar

Command strip with roving focus across buttons, links, inputs, groups, and separators.