Combobox
A text input with a list of suggestions to pick from, such as a searchable select.
Combobox follows the Combobox WAI-ARIA design pattern with list autocomplete.
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);
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
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/coreAnatomy#
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>
| Part | Element | Description |
|---|---|---|
Combobox.Root | <div> | Wraps the parts and holds the value, the text and the open state. |
Combobox.Label | <label> | The label of the input, also the name of the listbox. |
Combobox.Control | <div> | Wraps the input and the trigger. The listbox is placed below it. |
Combobox.Input | <input> | The text input. Focus stays here. |
Combobox.ClearTrigger | <button> | Optional. Clears the text and the value. Hidden while there is nothing to clear. |
Combobox.Trigger | <button> | Optional. Opens and closes the listbox. Not in the tab order. |
Combobox.HiddenInput | <input> | Optional. Submits the selected value with a form. |
Combobox.Content | <div> | The popup, a popover="manual" element in the top layer. |
Combobox.List | <div> | The listbox. |
Combobox.Item | <div> | An option. |
Combobox.ItemText | <span> | The text put in the input when the option is selected. |
Combobox.ItemIndicator | <span> | The check mark of the selected option, hidden otherwise. |
Combobox.Group | <div> | A group of options, named by its GroupLabel. |
Combobox.GroupLabel | <div> | The name of a group. Not an option. |
Combobox.Empty | <div> | The message when nothing matches. You decide when to render it. |
Filtering#
The combobox does not filter: render the items that match the text. onInputValueChange$ tells you the text and why it changed (reason): 'input' when the user typed, and 'select', 'clear' or 'blur' otherwise. Filter only on 'input', so the listbox shows all the items again when it opens after a selection. You can filter in any way, including with a request to a server.
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 also gives you the text, when you need to set it yourself.
When you set defaultValue (or bind:value), also set the text of that item with defaultInputValue (or bind:inputValue): the items are not known when the page is rendered on the server.
Typing does not select. When the input loses focus, its text goes back to the selected item, or the value is cleared when the input is empty.
Opening#
The listbox opens when the user types, presses ArrowDown or ArrowUp, or presses the Trigger. With openOnClick, clicking the input opens it too; the demo above uses it.
Examples#
Groups and Auto Highlight#
Combobox.Group and Combobox.GroupLabel group the options. With autoHighlight, typing highlights the first match, so Enter selects it. With loop, the arrow keys wrap around.
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 Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| ids | – | { label?: string; control?: string; input?: string; trigger?: string; list?: string } Overrides the element IDs of the parts. Inside a Field, the Field's ids are used. |
| defaultValue | – | string | null The value of the selected item initially (uncontrolled). |
| bind:value | – | Signal<string | null> A signal with the value of the selected item (controlled). |
| onValueChange$ | – | QRL<(value: string | null) => void> Called when the user selects an item or clears the combobox. |
| defaultInputValue | '' | string The text in the input initially (uncontrolled). With |
| bind:inputValue | – | Signal<string> A signal with the text in the input (controlled). Use it to filter the items. |
| onInputValueChange$ | – | QRL< (value: string, details: { reason: 'input' | 'select' | 'clear' | 'blur' }) => void > Called when the text in the input changes. |
| defaultOpen | false | boolean Whether the listbox is open initially (uncontrolled). |
| bind:open | – | Signal<boolean> A signal with the open state of the listbox (controlled). |
| onOpenChange$ | – | QRL<(open: boolean) => void> Called when the listbox opens or closes by a user interaction. |
| disabled | false | boolean Whether the combobox is disabled. |
| required | false | boolean Whether a value is required in a form. |
| loop | false | boolean Whether ArrowDown on the last item moves to the first one, and ArrowUp on the first to the last. |
| autoHighlight | false | boolean Whether typing highlights the first item, so Enter selects it. |
| openOnClick | false | boolean Whether clicking the input opens the listbox. |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox | Always present |
data-state | "open" | "closed" |
data-disabled | Present when disabled |
Label#
No props of its own. Accepts all <label> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-label | Always present |
data-disabled | Present when disabled |
Control#
No props of its own. Accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-control | Always present |
data-state | "open" | "closed" |
data-disabled | Present when disabled |
Input#
| Prop | Default | Type |
|---|---|---|
| invalid | – | boolean Whether the value is invalid. Inside a Field, the Field's |
Also accepts all <input> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-input | Always present |
data-state | "open" | "closed" |
data-disabled | Present when disabled |
data-invalid | Present when invalid |
Trigger#
No props of its own. Accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-trigger | Always present |
data-state | "open" | "closed" |
data-disabled | Present when disabled |
ClearTrigger#
No props of its own. Accepts all <button> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-clear-trigger | Always present |
data-state | "filled" | "empty" |
data-disabled | Present when disabled |
It has the hidden attribute while there is nothing to clear. If you set display on it, hide it again with [hidden] { display: none; }.
HiddenInput#
No props of its own. Accepts all <input> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-hidden-input | Always present |
It is positioned absolutely, so give the Root position: relative.
Content#
| Prop | Default | Type |
|---|---|---|
| side | 'bottom' | 'top' | 'right' | 'bottom' | 'left' The side of the Control to place the listbox on. It flips when there is no room. |
| align | 'start' | 'start' | 'center' | 'end' The alignment along that side. |
| sideOffset | 0 | number The distance from the Control in px. |
| alignOffset | 0 | number The offset along the side in px. |
| avoidCollisions | true | boolean Whether to flip and shift the listbox to keep it in the viewport. |
| collisionPadding | 0 | number The padding from the viewport edges when avoiding collisions, in px. |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-content | Always present |
data-state | "open" | "closed" |
data-side | The final side after flipping |
data-align | "start" | "center" | "end" |
| CSS variable | Value |
|---|---|
--leve-combobox-anchor-width | The width of the Control, for example to make the listbox as wide |
--leve-combobox-anchor-height | The height of the Control |
--leve-combobox-available-width | The width available in the viewport |
--leve-combobox-available-height | The height available in the viewport, for example for max-height |
List#
No props of its own. Accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-list | Always present |
Item#
| Prop | Default | Type |
|---|---|---|
| value (required) | – | string The value of the item. Unique in the combobox. |
| disabled | false | boolean Whether the item cannot be selected. Arrow keys skip it. |
| textValue | – | string The text put in the input when the item is selected, when it differs from the ItemText. |
Also accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-item | Always present |
data-value | The value |
data-state | "checked" | "unchecked" |
data-highlighted | Present on the highlighted option |
data-disabled | Present when disabled |
data-text-value | The textValue, when set |
Focus stays in the input, so style the highlighted option with [data-highlighted], not :focus.
ItemText#
No props of its own. Accepts all <span> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-item-text | Always present |
ItemIndicator#
No props of its own. Accepts all <span> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-item-indicator | Always present |
data-state | "checked" | "unchecked" |
Group#
No props of its own. Accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-group | Always present |
GroupLabel#
No props of its own. Accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-group-label | Always present |
Empty#
No props of its own. Accepts all <div> attributes.
| Data attribute | Value |
|---|---|
data-leve-combobox-empty | Always present |
Accessibility#
Complies with the Combobox WAI-ARIA design pattern.
Combobox.Inputrendersrole="combobox",aria-autocomplete="list",aria-expandedandaria-controls. Focus stays in the input, andaria-activedescendantpoints to the highlighted option.Combobox.Listrendersrole="listbox", named by the Label. Options renderrole="option"witharia-selected; disabled ones renderaria-disabled="true"and are skipped by the arrow keys.Combobox.Grouprendersrole="group", named by its GroupLabel.Combobox.ItemIndicatoris hidden from assistive technologies, sincearia-selectedconveys the state.- Inside a Field, the input takes the Field's id, label, description, error message,
invalid,disabledandrequired. Combobox.TriggerandCombobox.ClearTriggerare not in the tab order: from the input, the keyboard opens the listbox with ArrowDown and clears with Escape. Give them anaria-labelwhen they show only an icon.
Keyboard Interactions#
| Key | Description |
|---|---|
ArrowDown | Opens the listbox and highlights the first option, or highlights the next one. |
ArrowUp | Opens the listbox and highlights the last option, or highlights the previous one. |
Alt + ArrowDown | Opens the listbox without highlighting. |
Alt + ArrowUp | Closes the listbox. |
Enter | Selects the highlighted option, puts its text in the input and closes the listbox. |
Escape | Closes the listbox. When it is closed, clears the input and the value. |
| Characters | Type in the input, which opens the listbox. |