Edit Profile

Dark Mode

Copy config

Copy and paste the following code into your global.css file to apply the styles.

DISCLAIMER: This component is in
Beta
status. That means that it is ready for production, but the API might change.

Toggle Group

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

✨ Features

  • Follows the WAI-Aria design pattern
  • Full keyboard navigation
  • Can open one or multiple items at a time
  • Supports initial and reactive values
  • Supports looping
  • Choose the orientation and direction

Building blocks

import { component$ } from '@builder.io/qwik';
import { ToggleGroup } from '@qwik-ui/headless';

export default component$(() => {
  return (
    <ToggleGroup.Root>
      <ToggleGroup.Item value="left" aria-label="Left aligned">
        Left
      </ToggleGroup.Item>
      <ToggleGroup.Item value="center" aria-label="Center aligned">
        Center
      </ToggleGroup.Item>
      <ToggleGroup.Item value="right" aria-label="Right aligned">
        Right
      </ToggleGroup.Item>
    </ToggleGroup.Root>
  );
});

🎨 Anatomy

ComponentDescription
ToggleGroup.Root

The primary container for the toggle group.

ToggleGroup.Item

A single item.

Usage / Component State

Multiple selection

Pass a multiple prop to enable multi-selection.

Initial Value (Uncontrolled)

An initial, uncontrolled value can be provided using the value prop.

If you want to have some control when an item is selected, like making some side effect you can use the onChange$. The event is fired when the user toggle the button, and receives the new value.

You selected: left

Reactive Value (Controlled)

Pass a signal to bind:value prop to make the pressed state controlled (binding the value with a signal).

You selected: left

Disabled

Pass the disabled prop.

You can also disabled specific items, pass the disabled prop at the ToggleGroup.Item level: When navigating with key arrows, the disabled item will be skipped.

Looping Enabled

Pass the loop prop. When enabled, keyboard navigation will loop from last item to first, and vice versa. If one item is disabled it will skip it.

If one item is disabled it will skip it.

Vertical Orientation

Pass the orientation prop.

Right-to-Left (rtl) Direction

Pass the direction prop to rtl.

Accessibility

Keyboard interaction

Key

Description

Space
Toggles the item.
Enter
Toggles the item.
ArrowLeft
Works when orientation is "horizontal". Moves focus to the previous item. If direction is "rtl", moves focus to the next item.
ArrowRight
Works when orientation is "horizontal". Moves focus to the next item. If "rtl", moves focus to the previous item.
ArrowDown
Works when orientation is "vertical". Moves focus to the next item. If "rtl", moves focus to the previous item.
ArrowUp
Works when orientation is "vertical". Moves focus to the previous item. If "rtl", moves focus to the next item.

API

ToggleGroup.Root

PropTypeDescription
multiple
boolean

Enable multiple selections. Default to `false`.

value
string | string[]

Initial value to make the pressed state uncontrolled. Use in conjunction with `onChange$` to have some reactivity.

onChange$
function

Called when the state changes.

bind:value
Signal<string | string[]>

Reactive value (signal) to make the pressed state controlled.

disabled
boolean

Disables all items.

loop
boolean

Enable looping when navigating with the keyboard. Default to `false`.

orientation
"horizontal" | "vertical"

Choose the orientation of the toggle items. Default to "horizontal".

direction
"ltr" | "rtl"

Choose the direction of the toggle items. Default to "ltr".

ToggleGroup.Item

PropTypeDescription
value
string

A unique value for the item.

disabled
boolean

Disables the toggle making the toggle unpressable.

pressed
boolean

Makes the toggle initially pressed.