Toggle Group

A set of two-state buttons that can be toggled on or off.

<script setup lang="ts">
import { AToggleGroupItem, AToggleGroupRoot } from 'akar';
import { ref } from 'vue';

const toggleStateSingle = ref('left');
const toggleStateMultiple = ref(['italic']);

const toggleGroupItemClasses = 'color-text bg-background flex h-[35px] w-[35px] items-center justify-center bg-background text-base leading-4 first:rounded-l-[7px] last:rounded-r-[7px]  data-[state=on]:bg-background-accented hover:bg-background-elevated focus:(focus:z-10 ring-2 ring-ring-inverted)';
</script>

<template>
  <div>
    <AToggleGroupRoot
      v-model="toggleStateSingle"
      type="single"
      class="rounded-lg flex ring ring-ring-accented ring-inset shadow-sm"
    >
      <AToggleGroupItem
        value="left"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
      >
        <i
          class="i-lucide:text-align-start size-4"
        />
      </AToggleGroupItem>
      <AToggleGroupItem
        value="center"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
        class="border-x border-border-accented"
      >
        <i
          class="i-lucide:text-align-center size-4"
        />
      </AToggleGroupItem>
      <AToggleGroupItem
        value="right"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
      >
        <i
          class="i-lucide:text-align-end size-4"
        />
      </AToggleGroupItem>
    </AToggleGroupRoot>
    <br>
    <AToggleGroupRoot
      v-model="toggleStateMultiple"
      type="multiple"
      class="rounded-lg flex ring ring-ring-accented ring-inset shadow-sm"
    >
      <AToggleGroupItem
        value="bold"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
      >
        <i
          class="i-lucide:bold size-4"
        />
      </AToggleGroupItem>
      <AToggleGroupItem
        value="italic"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
        class="border-x border-border-accented"
      >
        <i
          class="i-lucide:italic size-4"
        />
      </AToggleGroupItem>
      <AToggleGroupItem
        value="strikethrough"
        aria-label="Toggle italic"
        :class="toggleGroupItemClasses"
      >
        <i
          class="i-lucide:strikethrough size-4"
        />
      </AToggleGroupItem>
    </AToggleGroupRoot>
  </div>
</template>

Features

Full keyboard navigation.
Supports horizontal/vertical orientation.
Support single and multiple pressed buttons.
Can be controlled or uncontrolled.

Anatomy

Import the component.

<script setup>
import { AToggleGroupItem, AToggleGroupRoot } from 'akar';
</script>

<template>
  <AToggleGroupRoot>
    <AToggleGroupItem />
  </AToggleGroupRoot>
</template>

API Reference

Root

Contains all the parts of a toggle group.

Props

Prop	Default	Type
`as`	`'div'`	`APrimitiveAsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`defaultValue`		`AcceptableValue \| AcceptableValue[]` The default active value of the item(s). Use when you do not need to control the state of the item(s).
`dir`		`'ltr' \| 'rtl'` The reading direction of the combobox when applicable. If omitted, inherits globally from `AConfigProvider` or assumes LTR (left-to-right) reading mode.
`disabled`	`false`	`boolean` When `true`, prevents the user from interacting with the toggle group and all its items.
`loop`	`true`	`boolean` When `loop` and `rovingFocus` is `true`, keyboard navigation will loop from last item to first, and vice versa.
`modelValue`		`AcceptableValue \| AcceptableValue[]`
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`orientation`		`'horizontal' \| 'vertical'` The orientation of the component, which determines how focus moves: `horizontal` for left/right arrows and `vertical` for up/down arrows.
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`rovingFocus`	`true`	`boolean` When `false`, navigating through the items using arrow keys will be disabled.
`type`		`'multiple' \| 'single'` Determines whether a 'single' or 'multiple' items can be pressed at a time. This prop will overwrite the inferred type from `modelValue` and `defaultValue`.

Emits

Event	Type
`update:modelValue`	`[payload: AcceptableValue \| AcceptableValue[]]` Event handler called when the value changes.

Slots

Slot	Type
`modelValue`	`AcceptableValue \| AcceptableValue[]` The controlled value of the active item(s). Use this when you need to control the state of the items. Can be binded with `v-model`

Item

An item in the group.

Props

Prop	Default	Type
`as`	`'button'`	`APrimitiveAsTag \| Component` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`		`boolean` Change the default rendered element for the one passed as a child, merging their props and behavior. Read our Composition guide for more details.
`disabled`		`boolean` When `true`, prevents the user from interacting with the toggle group and all its items.
`value*`		`AcceptableValue` A string value for the toggle group item. All items within a toggle group should use a unique value.

Slots

Slot	Type
`modelValue`	`boolean` The controlled value of the active item(s). Use this when you need to control the state of the items. Can be binded with `v-model`
`state`	`'on' \| 'off'` Current state
`pressed`	`boolean` Current pressed state
`disabled`	`boolean` When `true`, prevents the user from interacting with the toggle group and all its items.

Examples

Ensuring there is always a value

You can control the component to ensure a value.

<script setup>
import { AToggleGroupItem, AToggleGroupRoot } from 'akar';
import { ref } from 'vue';

const value = ref('left');
</script>

<template>
  <AToggleGroupRoot
    :model-value="value"
    @update:model-value="(val) => {
      if (val) value = val
    }"
  >
    <AToggleGroupItem value="left">
      <TextAlignLeftIcon />
    </AToggleGroupItem>
    <AToggleGroupItem value="center">
      <TextAlignCenterIcon />
    </AToggleGroupItem>
    <AToggleGroupItem value="right">
      <TextAlignRightIcon />
    </AToggleGroupItem>
  </AToggleGroupRoot>
</template>

Accessibility

Uses roving tabindex to manage focus movement among items.

Keyboard Interactions

Key	Description
`Tab`	Moves focus to either the pressed item or the first item in the group.
`Space`	Activates/deactivates the item.
`Enter`	Activates/deactivates the item.
`ArrowDown`	Moves focus to the next item in the group.
`ArrowRight`	Moves focus to the next item in the group.
`ArrowUp`	Moves focus to the previous item in the group.
`ArrowLeft`	Moves focus to the previous item in the group.
`Home`	Moves focus to the first item.
`End`	Moves focus to the last item.

Toggle

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

Alert Dialog

A modal dialog that interrupts the user with important content and expects a response.