ドキュメントを検索

Combobox

検索可能なセレクトなど、候補リストから選択できるテキスト入力です。

Comboboxは、リスト自動補完を備えたCombobox WAI-ARIAデザインパターンに準拠しています。

Apple
Banana
Blueberry
Cherry
Grape
Lemon
Orange
Peach

Selected: none

import { component$, useComputed$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@leve-ui/combobox';
import { LuCheck, LuChevronDown, LuX } from '@qwikest/icons/lucide';
import styles from './default.css?inline';

const FRUITS = [
  { value: 'apple', label: 'Apple' },
  { value: 'banana', label: 'Banana' },
  { value: 'blueberry', label: 'Blueberry' },
  { value: 'cherry', label: 'Cherry' },
  { value: 'grape', label: 'Grape' },
  { value: 'lemon', label: 'Lemon', disabled: true },
  { value: 'orange', label: 'Orange' },
  { value: 'peach', label: 'Peach' },
];

export default component$(() => {
  useStyles$(styles);
  const query = useSignal('');
  const value = useSignal<string | null>(null);
  // Filtering is yours. Filter only while the user types, so the list shows every fruit again
  // when it opens after a selection
  const items = useComputed$(() =>
    FRUITS.filter((fruit) => fruit.label.toLowerCase().includes(query.value.toLowerCase())),
  );

  return (
    <div class="combobox-default">
      <Combobox.Root
        bind:value={value}
        onInputValueChange$={(text, { reason }) => {
          query.value = reason === 'input' ? text : '';
        }}
        openOnClick
        class="combobox-default-root"
      >
        <Combobox.Label class="combobox-default-label">Fruit</Combobox.Label>
        <Combobox.Control class="combobox-default-control">
          <Combobox.Input placeholder="Search fruits" class="combobox-default-input" />
          <Combobox.ClearTrigger aria-label="Clear" class="combobox-default-clear">
            <LuX aria-hidden="true" class="combobox-default-icon" />
          </Combobox.ClearTrigger>
          <Combobox.Trigger aria-label="Show fruits" class="combobox-default-trigger">
            <LuChevronDown aria-hidden="true" class="combobox-default-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Content sideOffset={4} class="combobox-default-content">
          <Combobox.List class="combobox-default-list">
            {items.value.map((fruit) => (
              <Combobox.Item
                key={fruit.value}
                value={fruit.value}
                disabled={fruit.disabled}
                class="combobox-default-item"
              >
                <Combobox.ItemText>{fruit.label}</Combobox.ItemText>
                <Combobox.ItemIndicator class="combobox-default-indicator">
                  <LuCheck aria-hidden="true" class="combobox-default-icon" />
                </Combobox.ItemIndicator>
              </Combobox.Item>
            ))}
          </Combobox.List>
          {items.value.length === 0 && (
            <Combobox.Empty class="combobox-default-empty">No fruits found</Combobox.Empty>
          )}
        </Combobox.Content>
      </Combobox.Root>
      <p class="combobox-default-status">Selected: {value.value ?? 'none'}</p>
    </div>
  );
});

インストール#

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

pnpm add @leve-ui/combobox

構造#

import { Combobox } from '@leve-ui/combobox'; // or '@leve-ui/core'

<Combobox.Root>
  <Combobox.Label />
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.ClearTrigger />
    <Combobox.Trigger />
  </Combobox.Control>
  <Combobox.HiddenInput />
  <Combobox.Content>
    <Combobox.List>
      <Combobox.Item>
        <Combobox.ItemText />
        <Combobox.ItemIndicator />
      </Combobox.Item>
      <Combobox.Group>
        <Combobox.GroupLabel />
        <Combobox.Item />
      </Combobox.Group>
    </Combobox.List>
    <Combobox.Empty />
  </Combobox.Content>
</Combobox.Root>
パーツ要素説明
Combobox.Root<div>各パーツをラップし、値、テキスト、開閉状態を保持します。
Combobox.Label<label>入力のラベルであり、listboxの名前でもあります。
Combobox.Control<div>入力とトリガーをラップします。listboxはその下に配置されます。
Combobox.Input<input>テキスト入力です。フォーカスはここに留まります。
Combobox.ClearTrigger<button>任意。テキストと値をクリアします。クリアする対象がない間は非表示になります。
Combobox.Trigger<button>任意。listboxを開閉します。タブ順序には含まれません。
Combobox.HiddenInput<input>任意。選択された値をフォームと一緒に送信します。
Combobox.Content<div>トップレイヤーにあるpopover="manual"要素のポップアップです。
Combobox.List<div>listboxです。
Combobox.Item<div>選択肢です。
Combobox.ItemText<span>選択肢が選択されたときに入力欄に設定されるテキストです。
Combobox.ItemIndicator<span>選択された選択肢のチェックマークです。それ以外の場合は非表示になります。
Combobox.Group<div>GroupLabelによって名前が付けられる選択肢のグループです。
Combobox.GroupLabel<div>グループの名前です。選択肢ではありません。
Combobox.Empty<div>一致するものがない場合のメッセージです。レンダリングするタイミングは自由に決定できます。

フィルタリング#

Comboboxはフィルタリングを行いません。テキストに一致する項目をレンダリングしてください。onInputValueChange$によってテキストと変更された理由(reason)が分かります。ユーザーが入力をタイプした場合は'input'、それ以外の場合は'select'、'clear'、または'blur'になります。選択後に開いたときにListboxにすべての項目が再度表示されるように、'input'のときのみフィルタリングしてください。サーバーへのリクエストなど、任意の方法でフィルタリングできます。

const query = useSignal('');
const items = useComputed$(() =>
  FRUITS.filter((fruit) => fruit.label.toLowerCase().includes(query.value.toLowerCase())),
);

<Combobox.Root
  onInputValueChange$={(text, { reason }) => {
    query.value = reason === 'input' ? text : '';
  }}
>
  {/* ... */}
  {items.value.map((fruit) => <Combobox.Item key={fruit.value} value={fruit.value} />)}
</Combobox.Root>

テキストを自分で設定する必要がある場合は、bind:inputValueでもテキストを取得できます。

ページがサーバーでレンダリングされる時点ではアイテムが不明なため、defaultValue(またはbind:value)を設定する場合は、defaultInputValue(またはbind:inputValue)でそのアイテムのテキストも設定してください。

入力しても選択はされません。入力欄からフォーカスが外れると、テキストは選択されたアイテムに戻るか、入力欄が空の場合は値がクリアされます。

展開#

Listboxは、ユーザーが入力をタイプしたり、ArrowDownまたはArrowUpを押したり、Triggerを押したりしたときに開きます。openOnClickを使用すると、inputをクリックしても開くようになります。上のデモではこれを使用しています。

例#

グループと自動ハイライト#

Combobox.GroupとCombobox.GroupLabelは選択肢をグループ化します。autoHighlightを指定すると、入力時に最初の一致項目がハイライトされ、Enterで選択できるようになります。loopを指定すると、矢印キーによる移動がループします。

Americas
New York
Chicago
Los Angeles
São Paulo
Europe
London
Paris
Berlin
Asia
Tokyo
Seoul
Singapore

APIリファレンス#

Root#

Propデフォルト型
ids–{ label?: string; control?: string; input?: string; trigger?: string; list?: string }

パーツの要素IDをオーバーライドします。Field内では、Fieldのidsが使用されます。

defaultValue–string | null

初期状態で選択されている項目の値(非制御)。

bind:value–Signal<string | null>

選択されている項目の値を持つシグナル(制御)。何も選択されていない場合はnullになります。

onValueChange$–QRL<(value: string | null) => void>

ユーザーが項目を選択したとき、またはcomboboxをクリアしたときに呼び出されます。

defaultInputValue''string

初期状態のinput内のテキスト(非制御)。defaultValueを使用する場合は、その項目のテキストを渡します。

bind:inputValue–Signal<string>

input内のテキストを持つシグナル(制御)。項目のフィルタリングに使用します。

onInputValueChange$–QRL< (value: string, details: { reason: 'input' | 'select' | 'clear' | 'blur' }) => void >

inputのテキストが変更されたときに呼び出されます。reasonは理由を示し、ユーザーが入力をタイプした場合は'input'、それ以外の場合は'select'、'clear'、または'blur'になります。選択後にListboxが再度開いたときにすべての項目を表示するには、'input'のときのみフィルタリングしてください。

defaultOpenfalseboolean

初期状態でlistboxが開いているかどうか(非制御)。

bind:open–Signal<boolean>

listboxの開閉状態を持つシグナル(制御)。

onOpenChange$–QRL<(open: boolean) => void>

ユーザー操作によってlistboxが開閉したときに呼び出されます。

disabledfalseboolean

comboboxが無効化されているかどうか。

requiredfalseboolean

フォームで値が必須かどうか。

loopfalseboolean

最後の項目でArrowDownを押したときに最初の項目へ、最初の項目でArrowUpを押したときに最後の項目へ移動するかどうか。

autoHighlightfalseboolean

入力時に最初の項目をハイライト表示し、Enterで選択できるようにするかどうか。

openOnClickfalseboolean

inputのクリックによってListboxを開くかどうか。

すべての<div>属性も受け入れます。

データ属性値
data-leve-combobox常に存在
data-state"open" | "closed"
data-disabled無効時に存在

Label#

独自のpropはありません。 すべての<label>属性を受け入れます。

データ属性値
data-leve-combobox-label常に存在
data-disabled無効時に存在

Control#

独自のpropはありません。 すべての<div>属性を受け入れます。

データ属性値
data-leve-combobox-control常に存在
data-state"open" | "closed"
data-disabled無効時に存在

Input#

Propデフォルト型
invalid–boolean

値が無効かどうか。Field内では、Fieldのinvalidも適用されます。

すべての<input>属性も受け入れます。

データ属性値
data-leve-combobox-input常に存在
data-state"open" | "closed"
data-disabled無効時に存在
data-invalid無効な場合に存在

Trigger#

独自のpropはありません。 すべての<button>属性を受け入れます。

データ属性値
data-leve-combobox-trigger常に存在
data-state"open" | "closed"
data-disabled無効時に存在

ClearTrigger#

独自のpropはありません。 すべての<button>属性を受け入れます。

データ属性値
data-leve-combobox-clear-trigger常に存在
data-state"filled" | "empty"
data-disabled無効時に存在

クリアする対象がない間はhidden属性が付きます。displayを設定する場合は、[hidden] { display: none; }で再度非表示にしてください。

HiddenInput#

独自のpropはありません。 すべての<input>属性を受け入れます。

データ属性値
data-leve-combobox-hidden-input常に存在

絶対配置されるため、Rootにposition: relativeを指定してください。

Content#

Propデフォルト型
side'bottom''top' | 'right' | 'bottom' | 'left'

listboxを配置するControlの側面。スペースがない場合は反転します。

align'start''start' | 'center' | 'end'

その側に沿った配置方向。

sideOffset0number

Controlからの距離(px単位)。

alignOffset0number

側に沿ったオフセット(px)。

avoidCollisionstrueboolean

listboxをビューポート内に維持するために反転およびシフトするかどうか。

collisionPadding0number

衝突を防ぐ際のビューポート端からのパディング(px)。

すべての<div>属性も受け入れます。

データ属性値
data-leve-combobox-content常に存在
data-state"open" | "closed"
data-side反転後の最終的な配置面
data-align"start" | "center" | "end"
CSS変数値
--leve-combobox-anchor-width例えばlistboxの幅を同じにするための、Controlの幅
--leve-combobox-anchor-heightControlの高さ
--leve-combobox-available-widthビューポートで利用可能な幅
--leve-combobox-available-heightビューポート内で利用可能な高さ(max-heightなどに使用)

List#

独自のpropはありません。 すべての<div>属性を受け入れます。

データ属性値
data-leve-combobox-list常に存在

Item#

Propデフォルト型
value (必須)–string

項目の値。combobox内で一意です。

disabledfalseboolean

項目を選択できないかどうか。矢印キーでスキップされます。

textValue–string

項目が選択されたときにinputに入力されるテキスト(ItemTextと異なる場合)。

すべての<div>属性も受け入れます。

データ属性値
data-leve-combobox-item常に存在
data-valuevalue
data-state"checked" | "unchecked"
data-highlightedハイライトされた選択肢に存在します
data-disabled無効時に存在
data-text-value設定されている場合のtextValue

フォーカスは入力欄に留まるため、ハイライトされた選択肢のスタイルには:focusではなく[data-highlighted]を使用してください。

ItemText#

独自のpropはありません。 すべての<span>属性を受け入れます。

データ属性値
data-leve-combobox-item-text常に存在

ItemIndicator#

独自のpropはありません。 すべての<span>属性を受け入れます。

データ属性値
data-leve-combobox-item-indicator常に存在
data-state"checked" | "unchecked"

Group#

独自のpropはありません。 すべての<div>属性を受け入れます。

データ属性値
data-leve-combobox-group常に存在

GroupLabel#

独自のpropはありません。 すべての<div>属性を受け入れます。

データ属性値
data-leve-combobox-group-label常に存在

Empty#

独自のpropはありません。 すべての<div>属性を受け入れます。

データ属性値
data-leve-combobox-empty常に存在

アクセシビリティ#

Combobox WAI-ARIAデザインパターンに準拠しています。

  • Combobox.Inputはrole="combobox"、aria-autocomplete="list"、aria-expanded、aria-controlsをレンダリングします。フォーカスは入力欄に留まり、aria-activedescendantはハイライトされた選択肢を指します。
  • Combobox.ListはLabelによって名前が付けられたrole="listbox"をレンダリングします。選択肢はaria-selectedを持つrole="option"をレンダリングし、無効化された選択肢はaria-disabled="true"をレンダリングして矢印キーでスキップされます。
  • Combobox.GroupはそのGroupLabelによって名前が付けられたrole="group"をレンダリングします。aria-selectedが状態を伝えるため、Combobox.ItemIndicatorは支援技術から隠されます。
  • Field内では、入力欄はFieldのid、label、description、エラーメッセージ、invalid、disabled、requiredを引き継ぎます。
  • Combobox.TriggerとCombobox.ClearTriggerはタブオーダーに含まれません。inputからは、キーボードのArrowDownでListboxを開き、Escapeでクリアできます。アイコンのみを表示する場合はaria-labelを指定してください。

キーボード操作#

キー説明
ArrowDownlistboxを開いて最初の選択肢をハイライトするか、次の選択肢をハイライトします。
ArrowUplistboxを開いて最後の選択肢をハイライトするか、前の選択肢をハイライトします。
Alt + ArrowDownハイライトせずにlistboxを開きます。
Alt + ArrowUplistboxを閉じます。
Enterハイライト表示されたオプションを選択し、そのテキストをinputに入力してlistboxを閉じます。
Escapelistboxを閉じます。閉じているときは、inputと値をクリアします。
文字inputに入力すると、listboxが開きます。