Toggle Group

ToggleGroup manages pressed buttons with single or multiple selection, roving focus, form values, item slots, and cancelable changes.

Use Toggle Group for segmented controls and button groups. Use Checkbox Group for choices with form 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.

Usage

<script setup lang="ts">
import type { ToggleGroupModel } from "akaza-ui";
import { ToggleGroup } from "akaza-ui";
import { ref } from "vue";

const value = ref<ToggleGroupModel>("center");
const options = [
  { value: "left", label: "Left" },
  { value: "center", label: "Center" },
  { value: "right", label: "Right" },
];
</script>

<template>
  <ToggleGroup v-model="value" :options="options" :allow-empty="false" />
</template>

Examples

Single selection

Use type="single" for one pressed value. Set allow-empty="false" when one item must always stay selected.

<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>

Native Form Reset

Within Field, the group inherits name, required, disabled, label, and description metadata. An unnamed required group still participates in native validation. Invalid submission focuses an enabled toggle; disabled groups do not serialize selected values.

A native form reset restores the initial model and clears interaction state. Calling preventDefault() on the reset event preserves the current value. Reset updates v-model without emitting value-change.

API Reference

Props

Emits

Slots

UI Options

Styling Hooks

Plain class applies to the root group.

Keyboard