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>
);
});.toggle-group-default {
display: inline-flex;
gap: 2px;
padding: 3px;
border-radius: 8px;
background: light-dark(#f1f5f9, #ffffff14);
font-family: inherit;
}
.toggle-group-default-item {
display: inline-flex;
align-items: center;
gap: 6px;
padding: 6px 12px;
border: none;
border-radius: 6px;
background: transparent;
font: inherit;
font-size: 13px;
font-weight: 500;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.toggle-group-default-item:hover {
color: light-dark(#0f172a, #ffffff);
}
/* Pressed */
.toggle-group-default-item[data-state="on"] {
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
box-shadow: 0 1px 3px rgb(15 23 42 / 0.12);
}
.toggle-group-default-item:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toggle-group-default-item[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}
.toggle-group-default-icon {
width: 14px;
height: 14px;
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/toggle-groupnpm install @leve-ui/toggle-groupyarn add @leve-ui/toggle-groupbun add @leve-ui/toggle-grouppnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
import { ToggleGroup } from '@leve-ui/toggle-group'; // or '@leve-ui/core'
<ToggleGroup.Root>
<ToggleGroup.Item />
</ToggleGroup.Root>
| Part | Element | Description |
|---|---|---|
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
import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { ToggleGroup } from '@leve-ui/toggle-group';
import { LuAlignCenter, LuAlignLeft, LuAlignRight } from '@qwikest/icons/lucide';
import styles from './controlled.css?inline';
export default component$(() => {
useStyles$(styles);
const value = useSignal<string[]>(['left']);
return (
<div class="toggle-group-controlled-wrapper">
<ToggleGroup.Root
aria-label="Text alignment"
bind:value={value}
class="toggle-group-controlled"
>
<ToggleGroup.Item value="left" class="toggle-group-controlled-item" aria-label="Align left">
<LuAlignLeft class="toggle-group-controlled-icon" aria-hidden="true" />
Left
</ToggleGroup.Item>
<ToggleGroup.Item
value="center"
class="toggle-group-controlled-item"
aria-label="Align center"
>
<LuAlignCenter class="toggle-group-controlled-icon" aria-hidden="true" />
Center
</ToggleGroup.Item>
<ToggleGroup.Item
value="right"
class="toggle-group-controlled-item"
aria-label="Align right"
>
<LuAlignRight class="toggle-group-controlled-icon" aria-hidden="true" />
Right
</ToggleGroup.Item>
</ToggleGroup.Root>
<p class="toggle-group-controlled-output">
Selected: {value.value.length > 0 ? value.value.join(', ') : 'none'}
</p>
</div>
);
});.toggle-group-controlled-wrapper {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 12px;
font-family: inherit;
font-size: 14px;
}
.toggle-group-controlled {
display: inline-flex;
gap: 2px;
padding: 3px;
border-radius: 8px;
background: light-dark(#f1f5f9, #ffffff14);
}
.toggle-group-controlled-item {
display: inline-flex;
align-items: center;
gap: 6px;
padding: 6px 12px;
border: none;
border-radius: 6px;
background: transparent;
font: inherit;
font-size: 13px;
font-weight: 500;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.toggle-group-controlled-item:hover {
color: light-dark(#0f172a, #ffffff);
}
/* Pressed */
.toggle-group-controlled-item[data-state="on"] {
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
box-shadow: 0 1px 3px rgb(15 23 42 / 0.12);
}
.toggle-group-controlled-item:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toggle-group-controlled-item[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}
.toggle-group-controlled-icon {
width: 14px;
height: 14px;
}
.toggle-group-controlled-output {
margin: 0;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}Disabled#
disabled on an Item disables only that item. Arrow keys skip it. disabled on the Root disables every item.
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 './disabled.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<ToggleGroup.Root
aria-label="Text alignment"
defaultValue={['left']}
class="toggle-group-disabled"
>
<ToggleGroup.Item value="left" class="toggle-group-disabled-item" aria-label="Align left">
<LuAlignLeft class="toggle-group-disabled-icon" aria-hidden="true" />
Left
</ToggleGroup.Item>
<ToggleGroup.Item
value="center"
disabled
class="toggle-group-disabled-item"
aria-label="Align center"
>
<LuAlignCenter class="toggle-group-disabled-icon" aria-hidden="true" />
Center
</ToggleGroup.Item>
<ToggleGroup.Item value="right" class="toggle-group-disabled-item" aria-label="Align right">
<LuAlignRight class="toggle-group-disabled-icon" aria-hidden="true" />
Right
</ToggleGroup.Item>
</ToggleGroup.Root>
);
});.toggle-group-disabled {
display: inline-flex;
gap: 2px;
padding: 3px;
border-radius: 8px;
background: light-dark(#f1f5f9, #ffffff14);
font-family: inherit;
}
.toggle-group-disabled-item {
display: inline-flex;
align-items: center;
gap: 6px;
padding: 6px 12px;
border: none;
border-radius: 6px;
background: transparent;
font: inherit;
font-size: 13px;
font-weight: 500;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.toggle-group-disabled-item:hover {
color: light-dark(#0f172a, #ffffff);
}
/* Pressed */
.toggle-group-disabled-item[data-state="on"] {
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
box-shadow: 0 1px 3px rgb(15 23 42 / 0.12);
}
.toggle-group-disabled-item:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toggle-group-disabled-item[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}
.toggle-group-disabled-icon {
width: 14px;
height: 14px;
}Multiple#
type="multiple" lets any number of items be pressed at once.
import { component$, useStyles$ } from '@builder.io/qwik';
import { ToggleGroup } from '@leve-ui/toggle-group';
import { LuBold, LuItalic, LuUnderline } from '@qwikest/icons/lucide';
import styles from './multiple.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<ToggleGroup.Root
type="multiple"
aria-label="Text styles"
defaultValue={['bold']}
class="toggle-group-multiple"
>
<ToggleGroup.Item value="bold" class="toggle-group-multiple-item" aria-label="Bold text">
<LuBold class="toggle-group-multiple-icon" aria-hidden="true" />
Bold
</ToggleGroup.Item>
<ToggleGroup.Item value="italic" class="toggle-group-multiple-item" aria-label="Italic text">
<LuItalic class="toggle-group-multiple-icon" aria-hidden="true" />
Italic
</ToggleGroup.Item>
<ToggleGroup.Item
value="underline"
class="toggle-group-multiple-item"
aria-label="Underline text"
>
<LuUnderline class="toggle-group-multiple-icon" aria-hidden="true" />
Underline
</ToggleGroup.Item>
</ToggleGroup.Root>
);
});.toggle-group-multiple {
display: inline-flex;
gap: 2px;
padding: 3px;
border-radius: 8px;
background: light-dark(#f1f5f9, #ffffff14);
font-family: inherit;
}
.toggle-group-multiple-item {
display: inline-flex;
align-items: center;
gap: 6px;
padding: 6px 12px;
border: none;
border-radius: 6px;
background: transparent;
font: inherit;
font-size: 13px;
font-weight: 500;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.toggle-group-multiple-item:hover {
color: light-dark(#0f172a, #ffffff);
}
/* Pressed */
.toggle-group-multiple-item[data-state="on"] {
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
box-shadow: 0 1px 3px rgb(15 23 42 / 0.12);
}
.toggle-group-multiple-item:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toggle-group-multiple-item[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}
.toggle-group-multiple-icon {
width: 14px;
height: 14px;
}Vertical#
orientation="vertical" makes ArrowUp / ArrowDown move focus instead of ArrowLeft / ArrowRight. It sets data-orientation.
import { component$, useStyles$ } from '@builder.io/qwik';
import { ToggleGroup } from '@leve-ui/toggle-group';
import {
LuAlignVerticalJustifyCenter,
LuAlignVerticalJustifyEnd,
LuAlignVerticalJustifyStart,
} from '@qwikest/icons/lucide';
import styles from './vertical.css?inline';
export default component$(() => {
useStyles$(styles);
return (
<ToggleGroup.Root
orientation="vertical"
aria-label="Vertical text alignment"
defaultValue={['top']}
class="toggle-group-vertical"
>
<ToggleGroup.Item value="top" class="toggle-group-vertical-item" aria-label="Align top">
<LuAlignVerticalJustifyStart class="toggle-group-vertical-icon" aria-hidden="true" />
Top
</ToggleGroup.Item>
<ToggleGroup.Item value="middle" class="toggle-group-vertical-item" aria-label="Align middle">
<LuAlignVerticalJustifyCenter class="toggle-group-vertical-icon" aria-hidden="true" />
Middle
</ToggleGroup.Item>
<ToggleGroup.Item value="bottom" class="toggle-group-vertical-item" aria-label="Align bottom">
<LuAlignVerticalJustifyEnd class="toggle-group-vertical-icon" aria-hidden="true" />
Bottom
</ToggleGroup.Item>
</ToggleGroup.Root>
);
});.toggle-group-vertical {
display: inline-flex;
flex-direction: column;
gap: 2px;
padding: 3px;
border-radius: 8px;
background: light-dark(#f1f5f9, #ffffff14);
font-family: inherit;
}
.toggle-group-vertical-item {
display: inline-flex;
align-items: center;
gap: 6px;
padding: 6px 12px;
border: none;
border-radius: 6px;
background: transparent;
font: inherit;
font-size: 13px;
font-weight: 500;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
.toggle-group-vertical-item:hover {
color: light-dark(#0f172a, #ffffff);
}
/* Pressed */
.toggle-group-vertical-item[data-state="on"] {
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
box-shadow: 0 1px 3px rgb(15 23 42 / 0.12);
}
.toggle-group-vertical-item:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.toggle-group-vertical-item[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}
.toggle-group-vertical-icon {
width: 14px;
height: 14px;
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| type | 'single' | 'single' | 'multiple' How many items can be pressed at once.
- |
| 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. |
| disabled | false | boolean Disables all items. |
| orientation | 'horizontal' | 'horizontal' | 'vertical' The orientation of the group, which decides the arrow keys that move focus. |
| loop | true | boolean Whether arrow keys wrap from the last item to the first and vice versa. |
| rovingFocus | true | boolean Manages focus with a roving tabindex and arrow keys. When |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-toggle-group | Always present |
data-orientation | "horizontal" | "vertical" |
data-disabled | Present 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#
| Prop | Default | Type |
|---|---|---|
| value (required) | – | string The value of this item. |
| disabled | false | boolean Disables this item. |
Also accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-toggle-group-item | Always present |
data-state | "on" | "off" |
data-disabled | Present 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-labeloraria-labelledbyonToggleGroup.Root, which rendersrole="group". - Each
ToggleGroup.Itemis a<button type="button">witharia-pressed. Its text content is its accessible name. For icon-only items, passaria-labeland hide the icon witharia-hidden="true". - Disabled items use the native
disabledattribute, 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#
| Key | Description |
|---|---|
Tab | Moves focus into the group (to the tab stop item), or out of the group. |
Space / Enter | Presses or releases the focused item. |
ArrowRight / ArrowLeft | Horizontal only. Moves focus to the next / previous enabled item. Wraps around when loop is true. |
ArrowDown / ArrowUp | Vertical only. Moves focus to the next / previous enabled item. Wraps around when loop is true. |
Home | Moves focus to the first enabled item. |
End | Moves 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.