ドキュメントを検索

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>
  );
});

インストール#

個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。

pnpm add @leve-ui/toggle-group

構造#

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

Disabled#

Itemのdisabledはその項目のみを無効化します。矢印キーはそれをスキップします。Rootのdisabledはすべての項目を無効化します。

Multiple#

type="multiple"により、任意の数の項目を同時に押せるようになります。

垂直方向#

orientation="vertical"を指定すると、フォーカス移動がArrowLeft / ArrowRightではなくArrowUp / ArrowDownになります。data-orientationを設定します。

APIリファレンス#

Root#

Propデフォルト型
type'single''single' | 'multiple'

同時に押すことができるアイテムの数。 - 'single': 0個または1個のアイテム - 'multiple': 任意の数のアイテム

defaultValue[]string[]

初期状態で押されているアイテムの値(非制御)。

bind:value–Signal<string[]>

押されているアイテムの値を保持するシグナル(制御)。

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

押されているアイテムが変更されたときに呼び出されます。

disabledfalseboolean

すべてのアイテムを無効化します。

orientation'horizontal''horizontal' | 'vertical'

グループの向き。フォーカスを移動する矢印キーを決定します。

looptrueboolean

矢印キーで最後の項目から最初の項目へ、またはその逆にラップするかどうか。

rovingFocustrueboolean

roving tabindexと矢印キーでフォーカスを管理します。falseの場合、アイテムはtabIndexや矢印キーのハンドラーなしでレンダリングされ、各アイテムは通常のタブストップになります。Toolbarなどの親要素がフォーカスを管理する場合に使用します。

すべての<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

この項目の値。

disabledfalseboolean

このアイテムを無効化します。

すべての<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の場合にのみ動作します。