Search docs

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.

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

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/combobox

Anatomy#

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>
PartElementDescription
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.

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

API Reference#

Root#

PropDefaultType
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). null when nothing is selected.

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 defaultValue, pass the text of that item.

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. reason tells why: 'input' when the user typed, 'select', 'clear' or 'blur' otherwise. Filter only on 'input' to show all the items when the listbox opens again after a selection.

defaultOpenfalseboolean

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.

disabledfalseboolean

Whether the combobox is disabled.

requiredfalseboolean

Whether a value is required in a form.

loopfalseboolean

Whether ArrowDown on the last item moves to the first one, and ArrowUp on the first to the last.

autoHighlightfalseboolean

Whether typing highlights the first item, so Enter selects it.

openOnClickfalseboolean

Whether clicking the input opens the listbox.

Also accepts all <div> attributes.

Data attributeValue
data-leve-comboboxAlways present
data-state"open" | "closed"
data-disabledPresent when disabled

Label#

No props of its own. Accepts all <label> attributes.

Data attributeValue
data-leve-combobox-labelAlways present
data-disabledPresent when disabled

Control#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-combobox-controlAlways present
data-state"open" | "closed"
data-disabledPresent when disabled

Input#

PropDefaultType
invalid–boolean

Whether the value is invalid. Inside a Field, the Field's invalid also applies.

Also accepts all <input> attributes.

Data attributeValue
data-leve-combobox-inputAlways present
data-state"open" | "closed"
data-disabledPresent when disabled
data-invalidPresent when invalid

Trigger#

No props of its own. Accepts all <button> attributes.

Data attributeValue
data-leve-combobox-triggerAlways present
data-state"open" | "closed"
data-disabledPresent when disabled

ClearTrigger#

No props of its own. Accepts all <button> attributes.

Data attributeValue
data-leve-combobox-clear-triggerAlways present
data-state"filled" | "empty"
data-disabledPresent 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 attributeValue
data-leve-combobox-hidden-inputAlways present

It is positioned absolutely, so give the Root position: relative.

Content#

PropDefaultType
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.

sideOffset0number

The distance from the Control in px.

alignOffset0number

The offset along the side in px.

avoidCollisionstrueboolean

Whether to flip and shift the listbox to keep it in the viewport.

collisionPadding0number

The padding from the viewport edges when avoiding collisions, in px.

Also accepts all <div> attributes.

Data attributeValue
data-leve-combobox-contentAlways present
data-state"open" | "closed"
data-sideThe final side after flipping
data-align"start" | "center" | "end"
CSS variableValue
--leve-combobox-anchor-widthThe width of the Control, for example to make the listbox as wide
--leve-combobox-anchor-heightThe height of the Control
--leve-combobox-available-widthThe width available in the viewport
--leve-combobox-available-heightThe height available in the viewport, for example for max-height

List#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-combobox-listAlways present

Item#

PropDefaultType
value (required)–string

The value of the item. Unique in the combobox.

disabledfalseboolean

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 attributeValue
data-leve-combobox-itemAlways present
data-valueThe value
data-state"checked" | "unchecked"
data-highlightedPresent on the highlighted option
data-disabledPresent when disabled
data-text-valueThe 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 attributeValue
data-leve-combobox-item-textAlways present

ItemIndicator#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-combobox-item-indicatorAlways present
data-state"checked" | "unchecked"

Group#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-combobox-groupAlways present

GroupLabel#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-combobox-group-labelAlways present

Empty#

No props of its own. Accepts all <div> attributes.

Data attributeValue
data-leve-combobox-emptyAlways present

Accessibility#

Complies with the Combobox WAI-ARIA design pattern.

  • Combobox.Input renders role="combobox", aria-autocomplete="list", aria-expanded and aria-controls. Focus stays in the input, and aria-activedescendant points to the highlighted option.
  • Combobox.List renders role="listbox", named by the Label. Options render role="option" with aria-selected; disabled ones render aria-disabled="true" and are skipped by the arrow keys.
  • Combobox.Group renders role="group", named by its GroupLabel. Combobox.ItemIndicator is hidden from assistive technologies, since aria-selected conveys the state.
  • Inside a Field, the input takes the Field's id, label, description, error message, invalid, disabled and required.
  • Combobox.Trigger and Combobox.ClearTrigger are not in the tab order: from the input, the keyboard opens the listbox with ArrowDown and clears with Escape. Give them an aria-label when they show only an icon.

Keyboard Interactions#

KeyDescription
ArrowDownOpens the listbox and highlights the first option, or highlights the next one.
ArrowUpOpens the listbox and highlights the last option, or highlights the previous one.
Alt + ArrowDownOpens the listbox without highlighting.
Alt + ArrowUpCloses the listbox.
EnterSelects the highlighted option, puts its text in the input and closes the listbox.
EscapeCloses the listbox. When it is closed, clears the input and the value.
CharactersType in the input, which opens the listbox.