Toggle Group
単一または複数選択可能なトグルボタンのセットです。
トグルグループ向けのWAI-ARIA APGパターンはありません。Toggle Groupは、Toolbarパターンのようなロービングtabindexを備えたトグルボタンのグループです。
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;
}インストール#
個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。
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/core構造#
import { ToggleGroup } from '@leve-ui/toggle-group'; // or '@leve-ui/core'
<ToggleGroup.Root>
<ToggleGroup.Item />
</ToggleGroup.Root>
| パーツ | 要素 | 説明 |
|---|---|---|
ToggleGroup.Root | <div> | role="group"を持つグループ。押下されている値を保持します。 |
ToggleGroup.Item | <button> | aria-pressedを持つ単一のトグルボタン。 |
例#
Controlled#
bind: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#
Itemのdisabledはその項目のみを無効化します。矢印キーはそれをスキップします。Rootのdisabledはすべての項目を無効化します。
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"により、任意の数の項目を同時に押せるようになります。
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;
}垂直方向#
orientation="vertical"を指定すると、フォーカス移動がArrowLeft / ArrowRightではなくArrowUp / ArrowDownになります。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リファレンス#
Root#
| Prop | デフォルト | 型 |
|---|---|---|
| type | 'single' | 'single' | 'multiple' 同時に押すことができるアイテムの数。
- |
| defaultValue | [] | string[] 初期状態で押されているアイテムの値(非制御)。 |
| bind:value | – | Signal<string[]> 押されているアイテムの値を保持するシグナル(制御)。 |
| onValueChange$ | – | QRL<(value: string[]) => void> 押されているアイテムが変更されたときに呼び出されます。 |
| disabled | false | boolean すべてのアイテムを無効化します。 |
| orientation | 'horizontal' | 'horizontal' | 'vertical' グループの向き。フォーカスを移動する矢印キーを決定します。 |
| loop | true | boolean 矢印キーで最後の項目から最初の項目へ、またはその逆にラップするかどうか。 |
| rovingFocus | true | boolean roving tabindexと矢印キーでフォーカスを管理します。 |
すべての<div>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-toggle-group | 常に存在 |
data-orientation | "horizontal" | "vertical" |
data-disabled | 無効時に存在 |
値は常に押された項目の値の配列であり、type="single"の場合でも同様です(空または1つの値)。defaultValueで非制御、またはbind:valueで制御できます。onValueChange$は押された項目が変化したときに呼び出されます。type="single"では、押されている項目を押すと解除されます。
親がフォーカスを管理する場合はrovingFocus={false}を設定します。その場合、各アイテムはtabIndexや矢印キーのハンドラーなしでレンダリングされるため、個別のタブストップになります。Toolbar内では、アイテムが自動的にツールバーに参加し、ツールバーが全アイテム間でフォーカスを移動するため、設定は不要です。
Item#
| Prop | デフォルト | 型 |
|---|---|---|
| value (必須) | – | string この項目の値。 |
| disabled | false | boolean このアイテムを無効化します。 |
すべての<button>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-toggle-group-item | 常に存在 |
data-state | "on" | "off" |
data-disabled | アイテムまたはグループが無効化されている場合に存在 |
data-orientation | "horizontal" | "vertical" |
アクセシビリティ#
専用のWAI-ARIA APGパターンはありません。各項目はButton WAI-ARIAデザインパターン(トグルボタン)に準拠し、フォーカスはToolbarパターンのように移動します。
role="group"をレンダリングするToggleGroup.Rootに、aria-labelまたはaria-labelledbyでグループの名前を指定します。- 各
ToggleGroup.Itemはaria-pressedを持つ<button type="button">です。そのテキストコンテンツがアクセシブルな名前になります。アイコンのみの項目の場合は、aria-labelを渡し、アイコンをaria-hidden="true"で非表示にします。 - 無効化された項目はネイティブの
disabled属性を使用するため、フォーカスできません。 - タブシーケンスに入るのは1つの項目のみです。最後にフォーカスされた項目、最初に押された項目、または何も押されていない場合は最初の有効な項目です。
キーボード操作#
| キー | 説明 |
|---|---|
Tab | フォーカスをグループ内(タブストップの項目)へ移動、またはグループ外へ移動します。 |
Space / Enter | フォーカスされている項目を押す、または解除します。 |
ArrowRight / ArrowLeft | 水平方向のみ。フォーカスを次/前の有効な項目に移動します。loopがtrueの場合は最初または最後にループします。 |
ArrowDown / ArrowUp | 垂直方向のみ。フォーカスを次/前の有効な項目に移動します。loopがtrueの場合は最初または最後にループします。 |
Home | フォーカスを最初の有効な項目に移動します。 |
End | フォーカスを最後の有効な項目に移動します。 |
右から左(RTL)のテキストでは、ArrowRightとArrowLeftの動作が逆になります。矢印キー、Home、Endは、rovingFocusがtrueの場合にのみ動作します。