Combobox
検索可能なセレクトなど、候補リストから選択できるテキスト入力です。
Comboboxは、リスト自動補完を備えたCombobox WAI-ARIAデザインパターンに準拠しています。
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>
);
});.combobox-default {
display: flex;
flex-direction: column;
gap: 12px;
font-family: inherit;
}
.combobox-default-root {
display: flex;
flex-direction: column;
gap: 6px;
width: 240px;
}
.combobox-default-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
/* The Control wraps the input and the button; the listbox is placed below it */
.combobox-default-control {
display: flex;
align-items: center;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
}
.combobox-default-control:focus-within {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.combobox-default-input {
flex: 1;
min-width: 0;
padding: 8px 10px;
border: 0;
background: transparent;
font: inherit;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
outline: none;
}
.combobox-default-clear,
.combobox-default-trigger {
display: inline-flex;
padding: 8px;
border: 0;
background: transparent;
color: light-dark(#475569, #c9ddf0);
cursor: pointer;
}
/* The ClearTrigger has the hidden attribute while there is nothing to clear */
.combobox-default-clear[hidden] {
display: none;
}
.combobox-default-clear:hover,
.combobox-default-trigger:hover {
color: light-dark(#0f172a, #ffffff);
}
.combobox-default-icon {
width: 16px;
height: 16px;
}
/* The Content is a popover in the top layer; the library sets its position */
.combobox-default-content {
box-sizing: border-box;
width: var(--leve-combobox-anchor-width);
max-height: min(240px, var(--leve-combobox-available-height));
overflow-y: auto;
padding: 4px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
}
.combobox-default-item {
display: flex;
align-items: center;
justify-content: space-between;
padding: 6px 8px;
border-radius: 4px;
font-size: 14px;
cursor: default;
}
/* The highlighted item: arrow keys and the pointer move the highlight (focus stays in the input) */
.combobox-default-item[data-highlighted] {
background: #009dfd;
color: #ffffff;
}
.combobox-default-item[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}
.combobox-default-empty {
padding: 6px 8px;
font-size: 14px;
color: light-dark(#475569, #c9ddf0);
}
.combobox-default-status {
margin: 0;
font-size: 14px;
color: light-dark(#475569, #c9ddf0);
}インストール#
個別のパッケージをインストールするか、@leve-ui/coreを使用してすべてのコンポーネントを一度に取得します。
pnpm add @leve-ui/comboboxnpm install @leve-ui/comboboxyarn add @leve-ui/comboboxbun add @leve-ui/comboboxpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/core構造#
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を指定すると、矢印キーによる移動がループします。
import { component$, useComputed$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@leve-ui/combobox';
import { LuCheck } from '@qwikest/icons/lucide';
import styles from './grouped.css?inline';
const TIMEZONES = [
{ region: 'Americas', zones: ['New York', 'Chicago', 'Los Angeles', 'São Paulo'] },
{ region: 'Europe', zones: ['London', 'Paris', 'Berlin'] },
{ region: 'Asia', zones: ['Tokyo', 'Seoul', 'Singapore'] },
];
export default component$(() => {
useStyles$(styles);
const query = useSignal('');
const groups = useComputed$(() =>
TIMEZONES.map((group) => ({
...group,
zones: group.zones.filter((zone) => zone.toLowerCase().includes(query.value.toLowerCase())),
})).filter((group) => group.zones.length > 0),
);
return (
// autoHighlight: typing highlights the first match, so Enter selects it
<Combobox.Root
onInputValueChange$={(text, { reason }) => {
// Filter only while the user types
query.value = reason === 'input' ? text : '';
}}
autoHighlight
loop
class="combobox-grouped"
>
<Combobox.Label class="combobox-grouped-label">Time zone</Combobox.Label>
<Combobox.Control class="combobox-grouped-control">
<Combobox.Input placeholder="Type a city" class="combobox-grouped-input" />
</Combobox.Control>
<Combobox.Content sideOffset={4} class="combobox-grouped-content">
<Combobox.List>
{groups.value.map((group) => (
<Combobox.Group key={group.region} class="combobox-grouped-group">
<Combobox.GroupLabel class="combobox-grouped-group-label">
{group.region}
</Combobox.GroupLabel>
{group.zones.map((zone) => (
<Combobox.Item key={zone} value={zone} class="combobox-grouped-item">
<Combobox.ItemText>{zone}</Combobox.ItemText>
<Combobox.ItemIndicator>
<LuCheck aria-hidden="true" class="combobox-grouped-icon" />
</Combobox.ItemIndicator>
</Combobox.Item>
))}
</Combobox.Group>
))}
</Combobox.List>
{groups.value.length === 0 && (
<Combobox.Empty class="combobox-grouped-empty">No cities found</Combobox.Empty>
)}
</Combobox.Content>
</Combobox.Root>
);
});.combobox-grouped {
display: flex;
flex-direction: column;
gap: 6px;
width: 240px;
font-family: inherit;
}
.combobox-grouped-label {
font-size: 14px;
font-weight: 500;
color: light-dark(#0f172a, #ffffff);
}
/* The Control wraps the input and the button; the listbox is placed below it */
.combobox-grouped-control {
display: flex;
align-items: center;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
}
.combobox-grouped-control:focus-within {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
.combobox-grouped-input {
flex: 1;
min-width: 0;
padding: 8px 10px;
border: 0;
background: transparent;
font: inherit;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
outline: none;
}
.combobox-grouped-icon {
width: 16px;
height: 16px;
}
/* The Content is a popover in the top layer; the library sets its position */
.combobox-grouped-content {
box-sizing: border-box;
width: var(--leve-combobox-anchor-width);
max-height: min(240px, var(--leve-combobox-available-height));
overflow-y: auto;
padding: 4px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
}
.combobox-grouped-item {
display: flex;
align-items: center;
justify-content: space-between;
padding: 6px 8px;
border-radius: 4px;
font-size: 14px;
cursor: default;
}
/* The highlighted item: arrow keys and the pointer move the highlight (focus stays in the input) */
.combobox-grouped-item[data-highlighted] {
background: #009dfd;
color: #ffffff;
}
.combobox-grouped-item[data-disabled] {
opacity: 0.5;
cursor: not-allowed;
}
.combobox-grouped-group-label {
padding: 6px 8px 2px;
font-size: 12px;
font-weight: 600;
color: light-dark(#475569, #c9ddf0);
}
.combobox-grouped-empty {
padding: 6px 8px;
font-size: 14px;
color: light-dark(#475569, #c9ddf0);
}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> 選択されている項目の値を持つシグナル(制御)。何も選択されていない場合は |
| onValueChange$ | – | QRL<(value: string | null) => void> ユーザーが項目を選択したとき、またはcomboboxをクリアしたときに呼び出されます。 |
| defaultInputValue | '' | string 初期状態のinput内のテキスト(非制御)。 |
| bind:inputValue | – | Signal<string> input内のテキストを持つシグナル(制御)。項目のフィルタリングに使用します。 |
| onInputValueChange$ | – | QRL< (value: string, details: { reason: 'input' | 'select' | 'clear' | 'blur' }) => void > inputのテキストが変更されたときに呼び出されます。 |
| defaultOpen | false | boolean 初期状態でlistboxが開いているかどうか(非制御)。 |
| bind:open | – | Signal<boolean> listboxの開閉状態を持つシグナル(制御)。 |
| onOpenChange$ | – | QRL<(open: boolean) => void> ユーザー操作によってlistboxが開閉したときに呼び出されます。 |
| disabled | false | boolean comboboxが無効化されているかどうか。 |
| required | false | boolean フォームで値が必須かどうか。 |
| loop | false | boolean 最後の項目でArrowDownを押したときに最初の項目へ、最初の項目でArrowUpを押したときに最後の項目へ移動するかどうか。 |
| autoHighlight | false | boolean 入力時に最初の項目をハイライト表示し、Enterで選択できるようにするかどうか。 |
| openOnClick | false | boolean 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の |
すべての<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' その側に沿った配置方向。 |
| sideOffset | 0 | number Controlからの距離(px単位)。 |
| alignOffset | 0 | number 側に沿ったオフセット(px)。 |
| avoidCollisions | true | boolean listboxをビューポート内に維持するために反転およびシフトするかどうか。 |
| collisionPadding | 0 | number 衝突を防ぐ際のビューポート端からのパディング(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-height | Controlの高さ |
--leve-combobox-available-width | ビューポートで利用可能な幅 |
--leve-combobox-available-height | ビューポート内で利用可能な高さ(max-heightなどに使用) |
List#
独自のpropはありません。 すべての<div>属性を受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-combobox-list | 常に存在 |
Item#
| Prop | デフォルト | 型 |
|---|---|---|
| value (必須) | – | string 項目の値。combobox内で一意です。 |
| disabled | false | boolean 項目を選択できないかどうか。矢印キーでスキップされます。 |
| textValue | – | string 項目が選択されたときにinputに入力されるテキスト(ItemTextと異なる場合)。 |
すべての<div>属性も受け入れます。
| データ属性 | 値 |
|---|---|
data-leve-combobox-item | 常に存在 |
data-value | value |
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を指定してください。
キーボード操作#
| キー | 説明 |
|---|---|
ArrowDown | listboxを開いて最初の選択肢をハイライトするか、次の選択肢をハイライトします。 |
ArrowUp | listboxを開いて最後の選択肢をハイライトするか、前の選択肢をハイライトします。 |
Alt + ArrowDown | ハイライトせずにlistboxを開きます。 |
Alt + ArrowUp | listboxを閉じます。 |
Enter | ハイライト表示されたオプションを選択し、そのテキストをinputに入力してlistboxを閉じます。 |
Escape | listboxを閉じます。閉じているときは、inputと値をクリアします。 |
| 文字 | inputに入力すると、listboxが開きます。 |