Kappa / Toggle Group

Workspace viewOne selection

Showing board view

<script setup>
import { ref } from "vue";
import { ToggleGroup } from "@dicehub/kappa/components/toggle-group";

const view = ref(["board"]);
</script>

<template>
  <ToggleGroup.Root
    v-model="view"
    aria-label="View mode"
    variant="outline"
    spacing="none"
  >
    <ToggleGroup.Item value="list">List</ToggleGroup.Item>
    <ToggleGroup.Item value="board">Board</ToggleGroup.Item>
    <ToggleGroup.Item value="timeline">Timeline</ToggleGroup.Item>
  </ToggleGroup.Root>
</template>

Installation

Toggle Group is part of the main Kappa package. Ark UI owns selection, roving focus, and group semantics.

Barrel

import { ToggleGroup } from "@dicehub/kappa";

Granular

import { ToggleGroup } from "@dicehub/kappa/components/toggle-group";

Usage

Use a single-select group for a view switcher or a multiple-select group for independent filters. Give the root a concise accessible name.

<script setup>
import { ToggleGroup } from "@dicehub/kappa/components/toggle-group";
</script>

<template>
  <ToggleGroup.Root :default-value="['board']" aria-label="View mode">
    <ToggleGroup.Item value="list">List</ToggleGroup.Item>
    <ToggleGroup.Item value="board">Board</ToggleGroup.Item>
    <ToggleGroup.Item value="timeline">Timeline</ToggleGroup.Item>
  </ToggleGroup.Root>
</template>

Set spacing="none" for a connected control. Use variant="outline" when the group needs a clear boundary.

Composition

Typical part hierarchy

ToggleGroup.Root
├── ToggleGroup.Item
├── ToggleGroup.Item
├── ToggleGroup.Item
└── ToggleGroup.Context (optional)

<ToggleGroup.Root>
  <ToggleGroup.Item value="one">One</ToggleGroup.Item>
  <ToggleGroup.Item value="two">Two</ToggleGroup.Item>
</ToggleGroup.Root>

ToggleGroup.Root renders the Ark group element. Each ToggleGroup.Item renders a native button with radio semantics in single-select mode or pressed semantics in multiple-select mode.

Kappa adds visual options and token-based CSS. Ark UI remains the behavior authority, including controlled and uncontrolled values, disabled items, roving focus, and orientation-aware keyboard support.

Use ToggleGroup.Context for a renderless state readout. Use RootProvider with useToggleGroup when the machine must be created outside the template.

Examples

Multiple Selection

Set multiple when the selected array represents independent options, such as visible table columns.

Columns: status, owner

<script setup>
import { ref } from "vue";
import { ToggleGroup } from "@dicehub/kappa/components/toggle-group";

const columns = ref(["status", "owner"]);
</script>

<template>
  <ToggleGroup.Root v-model="columns" multiple aria-label="Visible columns">
    <ToggleGroup.Item value="status">Status</ToggleGroup.Item>
    <ToggleGroup.Item value="owner">Owner</ToggleGroup.Item>
    <ToggleGroup.Item value="updated">Updated</ToggleGroup.Item>
  </ToggleGroup.Root>
</template>

Vertical

Use the vertical orientation when the options belong in a compact side rail or stacked control.

<script setup>
import { ToggleGroup } from "@dicehub/kappa/components/toggle-group";
</script>

<template>
  <ToggleGroup.Root
    :default-value="['board']"
    aria-label="View mode"
    orientation="vertical"
    variant="outline"
  >
    <ToggleGroup.Item value="list">List</ToggleGroup.Item>
    <ToggleGroup.Item value="board">Board</ToggleGroup.Item>
    <ToggleGroup.Item value="timeline">Timeline</ToggleGroup.Item>
  </ToggleGroup.Root>
</template>

Sizes

Small, base, and large sizes keep the same Ark selection and focus behavior.

<script setup>
import { ToggleGroup } from "@dicehub/kappa/components/toggle-group";
</script>

<template>
  <ToggleGroup.Root :default-value="['base']" aria-label="Density" size="sm">
    <ToggleGroup.Item value="small">Small</ToggleGroup.Item>
    <ToggleGroup.Item value="base">Base</ToggleGroup.Item>
    <ToggleGroup.Item value="large">Large</ToggleGroup.Item>
  </ToggleGroup.Root>
</template>

States

Disabled groups and items keep their selection visible while blocking interaction.

Item disabled

Group disabled

<script setup>
import { ToggleGroup } from "@dicehub/kappa/components/toggle-group";
</script>

<template>
  <ToggleGroup.Root
    :default-value="['available']"
    aria-label="Unavailable options"
    variant="outline"
  >
    <ToggleGroup.Item value="available">Available</ToggleGroup.Item>
    <ToggleGroup.Item value="pending" disabled>Pending</ToggleGroup.Item>
  </ToggleGroup.Root>

  <ToggleGroup.Root
    :default-value="['locked']"
    aria-label="Locked choice"
    disabled
  >
    <ToggleGroup.Item value="locked">Locked</ToggleGroup.Item>
  </ToggleGroup.Root>
</template>

Controlled

Use v-model when the selected values belong to application state or need a live readout.

Selected: board

<script setup>
import { ref } from "vue";
import { ToggleGroup } from "@dicehub/kappa/components/toggle-group";

const selected = ref(["board"]);
</script>

<template>
  <ToggleGroup.Root v-model="selected" aria-label="View mode">
    <ToggleGroup.Item value="list">List</ToggleGroup.Item>
    <ToggleGroup.Item value="board">Board</ToggleGroup.Item>
  </ToggleGroup.Root>
  <output aria-live="polite">Selected: {{ selected.join(", ") }}</output>
</template>

Accessibility

Give the group an accessible name with a visible label, aria-label, or aria-labelledby.
Ark uses a roving tab stop, so Tab enters the group once and arrow keys move between enabled items.
Single-select groups expose radio semantics. Multiple-select groups expose pressed semantics.
Disabled roots and items keep their current state visible and are removed from keyboard interaction.
Focus-visible, forced-colors, reduced-motion, and dark-mode styles remain distinct.

Keyboard Support

Key	Behavior
`Tab`	Moves into or out of the group through the roving tab stop.
`Arrow keys`	Moves focus along the horizontal or vertical group axis.
`Home / End`	Moves focus to the first or last enabled item.
`Space / Enter`	Toggles or selects the focused item.

API Reference

ToggleGroup.Root

Prop	Type	Default	Description
`defaultValue`	`string[]`	`[]`	Initial selected values for an uncontrolled group.
`modelValue`	`string[]`	`—`	Controlled selected values. Use with v-model.
`multiple`	`boolean`	`false`	Allows more than one item to be selected.
`deselectable`	`boolean`	`true`	Allows the selected item to be cleared in single-select mode.
`orientation`	`"horizontal" \| "vertical"`	`"horizontal"`	Sets the layout and arrow-key axis.
`disabled`	`boolean`	`false`	Disables the group and all of its items.
`loopFocus / rovingFocus`	`boolean`	`true`	Controls arrow-key wrapping and roving tab focus.
`variant`	`"default" \| "outline"`	`"default"`	Selects the quiet or bordered Kappa treatment.
`size`	`"sm" \| "base" \| "lg"`	`"base"`	Selects the item height and text geometry.
`spacing`	`"none" \| "sm" \| "md"`	`"sm"`	Sets the gap between items. Use none for a connected group.
`id / ids / asChild`	`string / partial ID map / boolean`	`generated / false`	Overrides machine IDs or composes the root with a direct child.

ToggleGroup.Item

Prop	Type	Default	Description
`value`	`string`	`required`	Stable item value used in the selected array.
`disabled`	`boolean`	`false`	Blocks focus and selection for this item.
`asChild`	`boolean`	`false`	Composes item behavior with its direct child.

Parts

Part	Element	Description
`ToggleGroup.Root`	`div`	Owns selection state, group semantics, and roving focus.
`ToggleGroup.RootProvider`	`div`	Provides an externally created Ark toggle-group machine.
`ToggleGroup.Item`	`button`	Selectable item with radio or pressed semantics.
`ToggleGroup.Context`	`renderless`	Exposes the current value and Ark group API to a slot.

Events

Event	Payload	Description
`update:modelValue`	`string[]`	Updates v-model after a selection change.
`valueChange`	`ToggleGroupValueChangeDetails`	Reports the next selected value array.

Slots

Slot	Description
`Root.default`	ToggleGroup.Item elements or composed children.
`Item.default`	Visible text, icon, or both inside the item button.
`Context.default`	Receives the renderless group context.

Data Attributes

Attribute	Value	Description
`data-slot`	`"toggle-group" \| "toggle-group-item"`	Identifies Kappa root and item parts.
`data-scope / data-part`	`"toggle-group" / "root" \| "item"`	Ark UI anatomy markers.
`data-state`	`"on" \| "off"`	Exposes each item selection state.
`data-disabled`	`present`	Appears on disabled roots or items.
`data-orientation`	`"horizontal" \| "vertical"`	Exposes the group axis.
`data-variant / data-size / data-spacing`	`resolved option`	Exposes Kappa visual options on the root.

Exports

Export	Description
`ToggleGroup`	Compound Ark-backed selection group.
`ToggleGroupRoot / RootProvider / Item / Context`	Named component parts.
`ToggleGroupProps / ItemProps / ToggleGroupEmits / Slots`	Public Vue props, events, and slot contracts.
`ToggleGroupVariant / Size / Spacing`	Kappa visual option types.
`TOGGLE_GROUP_* / isToggleGroup* / resolveToggleGroup*`	Option lists, defaults, guards, and resolvers.
`useToggleGroup / useToggleGroupContext / toggleGroupAnatomy`	Ark UI composition exports.