Search docs

Toggle Group

A set of toggle buttons, single or multiple selection.

There is no WAI-ARIA APG pattern for toggle groups. Toggle Group is a group of toggle buttons with a roving tabindex like the Toolbar pattern.

import { component$, useStyles$ } from '@builder.io/qwik';
import { ToggleGroup } from '@leve-ui/toggle-group';
import { LuAlignCenter, LuAlignLeft, LuAlignRight } from '@qwikest/icons/lucide';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <ToggleGroup.Root
      aria-label="Text alignment"
      defaultValue={['left']}
      class="toggle-group-default"
    >
      <ToggleGroup.Item value="left" class="toggle-group-default-item" aria-label="Align left">
        <LuAlignLeft class="toggle-group-default-icon" aria-hidden="true" />
        Left
      </ToggleGroup.Item>
      <ToggleGroup.Item value="center" class="toggle-group-default-item" aria-label="Align center">
        <LuAlignCenter class="toggle-group-default-icon" aria-hidden="true" />
        Center
      </ToggleGroup.Item>
      <ToggleGroup.Item value="right" class="toggle-group-default-item" aria-label="Align right">
        <LuAlignRight class="toggle-group-default-icon" aria-hidden="true" />
        Right
      </ToggleGroup.Item>
    </ToggleGroup.Root>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/toggle-group

Anatomy#

import { ToggleGroup } from '@leve-ui/toggle-group'; // or '@leve-ui/core'

<ToggleGroup.Root>
  <ToggleGroup.Item />
</ToggleGroup.Root>
PartElementDescription
ToggleGroup.Root<div>The group, with role="group". Holds the pressed values.
ToggleGroup.Item<button>One toggle button, with aria-pressed.

Examples#

Controlled#

bind:value controls the pressed values with a signal. The text below the group shows the current value.

Selected: left

Disabled#

disabled on an Item disables only that item. Arrow keys skip it. disabled on the Root disables every item.

Multiple#

type="multiple" lets any number of items be pressed at once.

Vertical#

orientation="vertical" makes ArrowUp / ArrowDown move focus instead of ArrowLeft / ArrowRight. It sets data-orientation.

API Reference#

Root#

PropDefaultType
type'single''single' | 'multiple'

How many items can be pressed at once. - 'single': zero or one item - 'multiple': any number of items

defaultValue[]string[]

The values of the items pressed initially (uncontrolled).

bind:value–Signal<string[]>

A signal with the values of the pressed items (controlled).

onValueChange$–QRL<(value: string[]) => void>

Called when the pressed items change.

disabledfalseboolean

Disables all items.

orientation'horizontal''horizontal' | 'vertical'

The orientation of the group, which decides the arrow keys that move focus.

looptrueboolean

Whether arrow keys wrap from the last item to the first and vice versa.

rovingFocustrueboolean

Manages focus with a roving tabindex and arrow keys. When false, items are rendered without tabIndex or arrow key handlers and each item is a regular tab stop. Use this when a parent such as a Toolbar manages focus.

Also accepts all <div> attributes.

Data attributeValue
data-leve-toggle-groupAlways present
data-orientation"horizontal" | "vertical"
data-disabledPresent when disabled

The value is always an array of the pressed items' values, also with type="single" (empty or one value). It is uncontrolled with defaultValue, or controlled with bind:value. onValueChange$ is called when the pressed items change. With type="single", pressing the pressed item releases it.

Set rovingFocus={false} when a parent manages focus. The items are then rendered without tabIndex and arrow key handlers, so each item is a regular tab stop. Inside a Toolbar, you do not need it: the items join the toolbar automatically, and the toolbar moves focus across all of its items.

Item#

PropDefaultType
value (required)–string

The value of this item.

disabledfalseboolean

Disables this item.

Also accepts all <button> attributes.

Data attributeValue
data-leve-toggle-group-itemAlways present
data-state"on" | "off"
data-disabledPresent when the item or the group is disabled
data-orientation"horizontal" | "vertical"

Accessibility#

There is no dedicated WAI-ARIA APG pattern. Each item follows the Button WAI-ARIA design pattern (toggle button), and focus moves like in the Toolbar pattern.

  • Name the group with aria-label or aria-labelledby on ToggleGroup.Root, which renders role="group".
  • Each ToggleGroup.Item is a <button type="button"> with aria-pressed. Its text content is its accessible name. For icon-only items, pass aria-label and hide the icon with aria-hidden="true".
  • Disabled items use the native disabled attribute, so they are not focusable.
  • Only one item is in the tab sequence: the last focused item, the first pressed item, or the first enabled item when nothing is pressed.

Keyboard Interactions#

KeyDescription
TabMoves focus into the group (to the tab stop item), or out of the group.
Space / EnterPresses or releases the focused item.
ArrowRight / ArrowLeftHorizontal only. Moves focus to the next / previous enabled item. Wraps around when loop is true.
ArrowDown / ArrowUpVertical only. Moves focus to the next / previous enabled item. Wraps around when loop is true.
HomeMoves focus to the first enabled item.
EndMoves focus to the last enabled item.

In right-to-left text, ArrowRight and ArrowLeft are reversed. Arrow keys, Home and End only work when rovingFocus is true.