Combobox

Users can either type a value or pick one from a dropdown list.

Personal Trainers

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <Combobox.Root class="combobox-root">
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

✨ Features

WAI ARIA Combobox design pattern
Single and multiple selection
Reactive and initial value changes
Disabled items
Tab key focus management
Grouped items
Looping
Custom scroll behavior
Popover UI above all
Custom positioning (Popover)
Typeahead item selection and focus
Arrow key navigation and focus management
Open/Close popover by typing, focus, or manually
Custom filter function
Closes on no matching items

Roadmap

Browser autofill with hidden select
Form validation support
Custom placeholder

Building blocks

import { component$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck } from '@qwikest/icons/lucide';

export default component$(() => {
  return (
    <Combobox.Root>
      <Combobox.Label>label</Combobox.Label>

      <Combobox.Control>
        <Combobox.Input />
        <Combobox.Trigger>trigger</Combobox.Trigger>
      </Combobox.Control>

      <Combobox.Popover>
        <Combobox.Item>
          <Combobox.ItemLabel>item label</Combobox.ItemLabel>
          <Combobox.ItemIndicator>
            <LuCheck />
          </Combobox.ItemIndicator>
        </Combobox.Item>
      </Combobox.Popover>
    </Combobox.Root>
  );
});

🎨 Anatomy

Component	Description
`Combobox.Root`	Container for the Combobox.
`Combobox.Label`	Accessible label for the Combobox.
`Combobox.Control`	Central element around which other elements are positioned.
`Combobox.Trigger`	Opens and closes the Combobox.
`Combobox.Input`	Filters items and shows the selected value.
`Combobox.Popover`	Container for list items, positioned above other content. Also the popover.
`Combobox.Item`	item in the popover.
`Combobox.ItemLabel`	Label for an item.
`Combobox.ItemIndicator`	Indicates selection.
`Combobox.Group`	Groups related items.
`Combobox.GroupLabel`	Label for a group of items.
`Combobox.Description`	Displays the accessible description of the combobox.

Why use a headless Combobox?

A native combobox does not exist. The Open UI group has created a proposal for a new HTML element called combobox.

Passing data

To add data, use the <Combobox.Item> component inside of the popover.

Basic example

Personal Trainers

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  return (
    <Combobox.Root class="combobox-root">
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>

      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>

      <Combobox.Popover class="combobox-popover" gutter={8}>
        <Combobox.Item class="combobox-item">
          <Combobox.ItemLabel>Option 1</Combobox.ItemLabel>
        </Combobox.Item>

        <Combobox.Item class="combobox-item">
          <Combobox.ItemLabel>Option 2</Combobox.ItemLabel>
        </Combobox.Item>
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

By default, the content inside of the <Combobox.ItemLabel /> component is the item's value.

Mapping over data

Personal Trainers

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <Combobox.Root class="combobox-root">
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

You control how the data is rendered. Map over the data or render the items as you like.

Object example

Logged in users

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const users = [
    { name: 'Tim', status: '🟢' },
    { name: 'Ryan', status: '🔴' },
    { name: 'Jim', status: '🟡' },
    { name: 'Jessie', status: '🟢' },
    { name: 'Abby', status: '🟡' },
  ];

  return (
    <Combobox.Root class="combobox-root">
      <Combobox.Label class="combobox-label">Logged in users</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {users.map((user) => (
          <Combobox.Item key={user.name} class="combobox-item">
            <Combobox.ItemLabel>{user.name}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>{user.status}</Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Passing a distinct value

Personal Trainers

The selected value is: null

import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';

export default component$(() => {
  useStyles$(styles);
  const users = [
    { id: '0', label: 'Tim' },
    { id: '1', label: 'Ryan' },
    { id: '2', label: 'Jim' },
    { id: '3', label: 'Jessie' },
    { id: '4', label: 'Abby' },
  ];

  const selected = useSignal<string | null>(null);

  const handleChange$ = $((value: string) => {
    selected.value = value;
  });

  return (
    <>
      <Combobox.Root onChange$={handleChange$} class="combobox-root" value="Blackberry">
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {users.map((user) => (
            <Combobox.Item value={user.id} key={user.id} class="combobox-item">
              <Combobox.ItemLabel>{user.label}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <p>The selected value is: {selected.value ?? 'null'}</p>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

A distinct value is when one thing is displayed to the user, but another value is passed to the item.

By adding the value prop to the <Combobox.Item /> component, a distinct value is created.

Handling selection changes

Personal Trainers

You have changed 0 times

import { component$, useSignal, useStyles$, $ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const count = useSignal(0);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  const handleChange$ = $(() => {
    count.value++;
  });

  return (
    <>
      <Combobox.Root class="combobox-root" onChange$={handleChange$}>
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {fruits.map((fruit) => (
            <Combobox.Item key={fruit} class="combobox-item">
              <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <p>You have changed {count.value} times</p>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Use the onChange$ prop to listen for changes in the selected value. It provides the new selected value as an argument.

The example above increments a count when a new item is selected.

Component state

To add initial state, use the value prop on the <Combobox.Root /> component.

Uncontrolled / Initial value

Personal Trainers

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <Combobox.Root class="combobox-root" value="Blackberry">
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

The example above sets "Jessie" as the initial value, so it is selected and focused.

Controlled / Reactive value

To add reactive state, use the bind:value prop on the <Combobox.Root /> component.

Personal Trainers

Your favorite fruit is: Apricot

import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const selectedFruit = useSignal<string>('Apricot');

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <>
      <Combobox.Root class="combobox-root" bind:value={selectedFruit}>
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {fruits.map((fruit) => (
            <Combobox.Item key={fruit} class="combobox-item">
              <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <p>Your favorite fruit is: {selectedFruit.value}</p>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Programmatic changes

Optionally, the selected value can be programmatically updated by the signal.

Personal Trainers

import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
export default component$(() => {
  useStyles$(styles);
  const users = [
    { id: '0', name: 'Tim' },
    { id: '1', name: 'Ryan' }, // 👈 start with Ryan
    { id: '2', name: 'Jim' },
    { id: '3', name: 'Jessie' },
    { id: '4', name: 'Abby' },
  ];
  const selectedId = useSignal<string>('1');

  return (
    <>
      <Combobox.Root class="combobox-root" bind:value={selectedId}>
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {users.map((user) => (
            <Combobox.Item value={user.id} key={user.id} class="combobox-item">
              <Combobox.ItemLabel>{user.name}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <button onClick$={$(() => (selectedId.value = '4'))}>Change to Abby</button>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';
import { LuChevronDown, LuCheck } from '@qwikest/icons/lucide';

In the example above, clicking the "Change to Abby" button changes the selected value.

Disabled items

Personal Trainers

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <Combobox.Root class="combobox-root">
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit, index) => (
          <Combobox.Item
            disabled={
              index === 0 || index === 2 || index === fruits.length - 1 ? true : false
            }
            key={fruit}
            class="combobox-item"
          >
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Add the disabled prop to <Combobox.Item /> to disable items.

Disabled items cannot be selected or focused and are skipped during arrow key navigation.

Dynamically adding items

A common use case is adding items dynamically, like an infinite scrolling list of users.

Fruits

import { $, component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuChevronDown, LuCheck } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const fruits = useSignal<string[]>([
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ]);
  const hasAddedFruits = useSignal<boolean>(false);

  return (
    <>
      <Combobox.Root class="combobox-root">
        <Combobox.Label class="combobox-label">Fruits</Combobox.Label>
        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {fruits.value.map((fruit) => (
            <Combobox.Item key={fruit} class="combobox-item">
              <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <button
        onClick$={$(() => {
          if (!hasAddedFruits.value) {
            fruits.value = [...fruits.value, 'Durian', 'Jackfruit', 'Ackee'];
            hasAddedFruits.value = true;
          }
        })}
      >
        Add Fruits
      </button>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Clicking the Add Users button creates new users to the list. We could also fetch more data from the server or database.

Item indicators

Personal Trainers

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <Combobox.Root class="combobox-root">
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>

      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>

      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Add <Combobox.ItemIndicator /> inside <Combobox.Item /> to indicate the selected item.

Multiple selections

To allow multiple selections, set the multiple prop to true.

Personal Trainers

import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown, LuX } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  const displayValues = useSignal<string[]>([]);
  const selected = useSignal<string[]>([]);

  const inputRef = useSignal<HTMLInputElement>();

  return (
    <Combobox.Root
      class="combobox-root"
      multiple
      removeOnBackspace
      bind:displayValue={displayValues}
      bind:value={selected}
    >
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
      <Combobox.Control class="combobox-control combobox-multiple">
        <div class="combobox-pill-container">
          {displayValues.value.map((item) => (
            <span class="combobox-pill" key={item}>
              {item}
              <span
                onPointerDown$={() => {
                  selected.value = selected.value?.filter(
                    (selectedItem) => selectedItem !== item,
                  );
                  inputRef.value?.focus();
                }}
              >
                <LuX aria-hidden="true" />
              </span>
            </span>
          ))}
          {displayValues.value.length > 4 && (
            <button
              class="combobox-clear combobox-pill"
              onClick$={() => {
                selected.value = [];
                inputRef.value?.focus();
              }}
            >
              clear all
            </button>
          )}
        </div>
        <Combobox.Input class="combobox-input" ref={inputRef} />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Use the bind:displayValue signal to configure multiple display values.

You can combine bind:value and bind:displayValue to create a custom widget that displays selected values as a list of pills.

Remove items on backspace

To remove items on backspace, add the removeOnBackspace prop to the <Combobox.Root /> component.

Personal Trainers

import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown, LuX } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  const displayValues = useSignal<string[]>([]);
  const selected = useSignal<string[]>([]);

  const inputRef = useSignal<HTMLInputElement>();

  return (
    <Combobox.Root
      class="combobox-root"
      multiple
      removeOnBackspace
      bind:displayValue={displayValues}
      bind:value={selected}
    >
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
      <Combobox.Control class="combobox-control combobox-multiple">
        <div class="combobox-pill-container">
          {displayValues.value.map((item) => (
            <span class="combobox-pill" key={item}>
              {item}
              <span
                onPointerDown$={() => {
                  selected.value = selected.value?.filter(
                    (selectedItem) => selectedItem !== item,
                  );
                  inputRef.value?.focus();
                }}
              >
                <LuX aria-hidden="true" />
              </span>
            </span>
          ))}
          {displayValues.value.length > 4 && (
            <button
              class="combobox-clear combobox-pill"
              onClick$={() => {
                selected.value = [];
                inputRef.value?.focus();
              }}
            >
              clear all
            </button>
          )}
        </div>
        <Combobox.Input class="combobox-input" ref={inputRef} />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Placeholder

We can provide a custom placeholder to the <Combobox.Root /> component by adding the placeholder prop.

Personal Trainers

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <Combobox.Root class="combobox-root" placeholder="placeholder">
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>

      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>

      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

CSR

Like every Qwik UI component, the Combobox component can be rendered server-side or client-side.

import { component$, useStyles$, useSignal } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const renderCombobox = useSignal(false);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <>
      <button onClick$={() => (renderCombobox.value = true)}>CSR mode</button>
      {renderCombobox.value && (
        <Combobox.Root class="combobox-root">
          <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>

          <Combobox.Control class="combobox-control">
            <Combobox.Input class="combobox-input" />
            <Combobox.Trigger class="combobox-trigger">
              <LuChevronDown class="combobox-icon" />
            </Combobox.Trigger>
          </Combobox.Control>

          <Combobox.Popover class="combobox-popover" gutter={8}>
            {fruits.map((fruit) => (
              <Combobox.Item key={fruit} class="combobox-item">
                <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
                <Combobox.ItemIndicator>
                  <LuCheck />
                </Combobox.ItemIndicator>
              </Combobox.Item>
            ))}
          </Combobox.Popover>
        </Combobox.Root>
      )}
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Custom Filter

By default, the Combobox filters items based on user input. To disable this, set the filter prop to false.

Personal Trainers

import { component$, useSignal, useStyles$, useTask$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';
import { matchSorter } from 'match-sorter';

export default component$(() => {
  useStyles$(styles);

  const inputValue = useSignal('');
  const filteredItems = useSignal<string[]>([]);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  useTask$(({ track }) => {
    track(() => inputValue.value);

    filteredItems.value = matchSorter(fruits, inputValue.value);
  });

  return (
    <Combobox.Root class="combobox-root" filter={false}>
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input bind:value={inputValue} class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {filteredItems.value.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

You can use any filtering library. In the example above, we use match-sorter.

Empty UI

By default, the popover automatically closes when there are no items to display.

To show UI when there are no items in the popover, use the Combobox.Empty component.

Personal Trainers

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <Combobox.Root class="combobox-root">
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
        <Combobox.Empty>No items found</Combobox.Empty>
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

To handle the popover open/close state, use the onOpenChange$ prop. It passes a boolean indicating whether the popover is open.

Personal Trainers

The listbox opened and closed 0 time(s)

import { component$, useSignal, useStyles$, $ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const count = useSignal(0);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  const handleOpenChange$ = $(() => {
    count.value++;
  });

  return (
    <>
      <Combobox.Root class="combobox-root" onOpenChange$={handleOpenChange$}>
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {fruits.map((fruit) => (
            <Combobox.Item key={fruit} class="combobox-item">
              <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <p>The listbox opened and closed {count.value} time(s)</p>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Reactive open state

To reactively control the open state, use the bind:open prop.

Personal Trainers

import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const isOpen = useSignal(false);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <>
      <Combobox.Root class="combobox-root" bind:open={isOpen}>
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {fruits.map((fruit) => (
            <Combobox.Item key={fruit} class="combobox-item">
              <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <button onClick$={() => (isOpen.value = !isOpen.value)}>Toggle open state</button>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Handling input changes

Add the onInput$ prop to the <Combobox.Root /> component.

onInput$ value:

Personal Trainers

onInput$ was called 0 time(s)

import { component$, useSignal, useStyles$, $ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const count = useSignal(0);
  const inputValue = useSignal('');

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  const handleInput$ = $((value: string) => {
    count.value++;
    inputValue.value = value;
  });

  return (
    <>
      <Combobox.Root class="combobox-root" onInput$={handleInput$}>
        <div>onInput$ value: {inputValue.value}</div>
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>

        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>

        <Combobox.Popover class="combobox-popover" gutter={8}>
          {fruits.map((fruit) => (
            <Combobox.Item key={fruit} class="combobox-item">
              <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <p>onInput$ was called {count.value} time(s)</p>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

This function is called when the user types in the input.

Reactive input value

The input can also be fully controlled by adding the bind:value prop to the <Combobox.Input /> component.

Personal Trainers

Typed input string: aba

import { component$, useSignal, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const inputStr = useSignal<string>('aba');

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <>
      <Combobox.Root class="combobox-root">
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
        <Combobox.Control class="combobox-control">
          <Combobox.Input bind:value={inputStr} class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {fruits.map((fruit) => (
            <Combobox.Item key={fruit} class="combobox-item">
              <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <p>Typed input string: {inputStr.value}</p>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Looping

To loop through items, use the loop prop on <Combobox.Root />.

Personal Trainers

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <Combobox.Root class="combobox-root" loop>
      <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        {fruits.map((fruit) => (
          <Combobox.Item key={fruit} class="combobox-item">
            <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
            <Combobox.ItemIndicator>
              <LuCheck />
            </Combobox.ItemIndicator>
          </Combobox.Item>
        ))}
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Pressing the down arrow key moves focus to the first enabled item.
Pressing the up arrow key moves focus to the last enabled item.

Grouped Items

Use <Combobox.Group /> and <Combobox.GroupLabel /> to group items and provide an accessible name.

User count

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const activeUsers = ['Tim', 'Ryan', 'Jim', 'Abby'];
  const offlineUsers = ['Joey', 'Bob', 'Jack', 'John'];

  return (
    <Combobox.Root class="combobox-root">
      <Combobox.Label class="combobox-label">User count</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover" gutter={8}>
        <Combobox.Group>
          <Combobox.GroupLabel class="combobox-group-label">Active</Combobox.GroupLabel>
          {activeUsers.map((user) => (
            <Combobox.Item key={user}>
              <Combobox.ItemLabel>{user}</Combobox.ItemLabel>
            </Combobox.Item>
          ))}
        </Combobox.Group>
        <Combobox.Group>
          <Combobox.GroupLabel class="combobox-group-label">Offline</Combobox.GroupLabel>
          {offlineUsers.map((user) => (
            <Combobox.Item key={user}>
              <Combobox.ItemLabel>{user}</Combobox.ItemLabel>
            </Combobox.Item>
          ))}
        </Combobox.Group>
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Scrolling

Handle scrolling in the popover since focus remains on the select trigger when open.

User count

import { component$, useStyles$ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const activeUsers = ['Tim', 'Ryan', 'Jim', 'Abby'];
  const offlineUsers = ['Joey', 'Bob', 'Jack', 'John'];

  return (
    <Combobox.Root class="combobox-root">
      <Combobox.Label class="combobox-label">User count</Combobox.Label>
      <Combobox.Control class="combobox-control">
        <Combobox.Input class="combobox-input" />
        <Combobox.Trigger class="combobox-trigger">
          <LuChevronDown class="combobox-icon" />
        </Combobox.Trigger>
      </Combobox.Control>
      <Combobox.Popover class="combobox-popover combobox-max-height" gutter={8}>
        <Combobox.Group>
          <Combobox.GroupLabel class="combobox-group-label">Active</Combobox.GroupLabel>
          {activeUsers.map((user) => (
            <Combobox.Item key={user}>
              <Combobox.ItemLabel>{user}</Combobox.ItemLabel>
            </Combobox.Item>
          ))}
        </Combobox.Group>

        <Combobox.Group>
          <Combobox.GroupLabel class="combobox-group-label">Offline</Combobox.GroupLabel>
          {offlineUsers.map((user) => (
            <Combobox.Item key={user}>
              <Combobox.ItemLabel>{user}</Combobox.ItemLabel>
            </Combobox.Item>
          ))}
        </Combobox.Group>
      </Combobox.Popover>
    </Combobox.Root>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

The native scrollIntoView method scrolls items into view when highlighted. To customize scroll behavior, add the scrollOptions prop to <Combobox.Root />.

When a value is not selected, the placeholder is displayed.

Advanced

Using Refs (experimental)

You can pass a ref to each Combobox component to access the underlying DOM element. This is an experimental feature, and we are still working on it, use at your own risk.

Personal Trainers

Click the trigger to change the background color

import { component$, useSignal, useStyles$, $ } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);

  const triggerRef = useSignal<HTMLButtonElement>();

  const handleClick$ = $(() => {
    if (!triggerRef.value) return;

    triggerRef.value.style.backgroundColor = 'red';
  });

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  return (
    <>
      <Combobox.Root class="combobox-root">
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger
            class="combobox-trigger"
            onClick$={handleClick$}
            ref={triggerRef}
          >
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {fruits.map((fruit) => (
            <Combobox.Item key={fruit} class="combobox-item">
              <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <p>Click the trigger to change the background color</p>
    </>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

Above is an example that programmatically changes the background color of the trigger when clicked.

Forms

To use the combobox in a form, a visually hidden native select element is provided inside of <Combobox.HiddenNativeSelect>.

import { component$, useStyles$, $, useSignal } from '@builder.io/qwik';
import { Combobox } from '@qwik-ui/headless';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';

export default component$(() => {
  useStyles$(styles);
  const submittedData = useSignal<string>();

  const fruits = [
    'Apple',
    'Apricot',
    'Bilberry',
    'Blackberry',
    'Blackcurrant',
    'Currant',
    'Cherry',
    'Coconut',
  ];

  const formName = 'combobox-form-name';

  const handleSubmit$ = $((e: SubmitEvent) => {
    const formData = new FormData(e.target as HTMLFormElement);
    const selectedFruit = formData.get(formName) as string;
    submittedData.value = selectedFruit ?? undefined;
  });

  return (
    <form onSubmit$={handleSubmit$} preventdefault:submit>
      <Combobox.Root name={formName} class="combobox-root">
        <Combobox.Label class="combobox-label">Personal Trainers</Combobox.Label>
        <Combobox.HiddenNativeSelect />
        <Combobox.Control class="combobox-control">
          <Combobox.Input class="combobox-input" />
          <Combobox.Trigger class="combobox-trigger">
            <LuChevronDown class="combobox-icon" />
          </Combobox.Trigger>
        </Combobox.Control>
        <Combobox.Popover class="combobox-popover" gutter={8}>
          {fruits.map((fruit) => (
            <Combobox.Item key={fruit} class="combobox-item">
              <Combobox.ItemLabel>{fruit}</Combobox.ItemLabel>
              <Combobox.ItemIndicator>
                <LuCheck />
              </Combobox.ItemIndicator>
            </Combobox.Item>
          ))}
        </Combobox.Popover>
      </Combobox.Root>
      <button type="submit">Submit my form!</button>
      {submittedData.value && (
        <div>
          <strong>You submitted:</strong>
          <code>{JSON.stringify(submittedData.value)}</code>
        </div>
      )}
    </form>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

The name prop on the Combobox.Root component is used to name the Combobox form field.

Validation

Form libaries like Modular Forms can be used to validate the combobox form field.

import { component$, useStyles$, $ } from '@builder.io/qwik';
import { LuCheck, LuChevronDown } from '@qwikest/icons/lucide';
import { Combobox } from '@qwik-ui/headless';
import { useForm, required } from '@modular-forms/qwik';

type Users = {
  firstName: string;
};

export default component$(() => {
  const users = ['Tim', 'Ryan', 'Jim', 'Jessie', 'Abby'];
  const [, { Form, Field }] = useForm<Users>({
    loader: { value: { firstName: '' } },
  });

  useStyles$(styles);

  const handleSubmit$ = $(() => {
    console.log('submitted!');
  });

  return (
    <Form onSubmit$={handleSubmit$}>
      <Field
        name="firstName"
        type="string"
        validate={[required<string>('Make sure to select an option')]}
      >
        {(field, props) => {
          return (
            <Combobox.Root class="combobox-root">
              <Combobox.Label class="combobox-label">Logged in users</Combobox.Label>
              <Combobox.HiddenNativeSelect {...props} />
              <Combobox.Control class="combobox-control">
                <Combobox.Input class="combobox-input" />
                <Combobox.Trigger class="combobox-trigger">
                  <LuChevronDown class="combobox-icon" />
                </Combobox.Trigger>
              </Combobox.Control>
              {field.error && (
                <Combobox.ErrorMessage style={{ color: '#D2122E' }}>
                  {field.error}
                </Combobox.ErrorMessage>
              )}
              <Combobox.Popover class="combobox-popover" gutter={8}>
                {users.map((user) => (
                  <Combobox.Item key={user} class="combobox-item">
                    <Combobox.ItemLabel>{user}</Combobox.ItemLabel>
                    <Combobox.ItemIndicator>
                      <LuCheck />
                    </Combobox.ItemIndicator>
                  </Combobox.Item>
                ))}
              </Combobox.Popover>
            </Combobox.Root>
          );
        }}
      </Field>
      <button type="submit">Submit my form!</button>
    </Form>
  );
});

// internal
import styles from '../snippets/combobox.css?inline';

When the <Combobox.ErrorMessage> component is rendered, the component is in an invalid state.

Example CSS

Every code example uses the following CSS:

:root {
  --combobox-width: 12rem;
}

.combobox-root {
  min-width: var(--combobox-width);
}

.combobox-input {
  all: unset;
  box-sizing: border-box;
  background: transparent;
  padding-inline: 0.5rem;
  padding-right: 44px;
}

.combobox-trigger {
  border-radius: calc(var(--border-radius) / 2);
  width: 44px;
  background: hsla(var(--primary) / 0.1);
  display: flex;
  align-items: center;
  justify-content: center;
  border-left: 2px dotted hsla(var(--foreground));
  position: absolute;
  right: 0;
}

.combobox-trigger[data-open] svg {
  transform: rotate(180deg);
}

.combobox-trigger,
.combobox-input {
  height: 44px;
}

.combobox-control {
  min-height: 48px;
  display: flex;
  align-items: center;
  outline: 2px dotted hsla(var(--foreground));
  position: relative;
}

.combobox-control:focus-within {
  background: hsl(var(--primary) / 0.08);
}

.combobox-control[data-invalid] {
  outline: 2px dotted #d2122e;
}

.combobox-popover {
  width: 100%;
  max-width: calc(var(--combobox-width) + 2.5rem);
  background-color: hsl(var(--background));
  padding: 0.5rem;
  border: 2px dotted hsla(var(--foreground) / 0.6);
  border-radius: calc(var(--border-radius) / 2);
  color: hsl(var(--foreground));
}

.combobox-icon {
  width: 1.5rem;
  height: 1.5rem;
  stroke: hsl(var(--foreground));
}

.combobox-trigger[data-open] .combobox-icon {
  transform: rotate(180deg);
}

.combobox-item {
  display: flex;
  align-items: center;
  justify-content: space-between;
}

.combobox-label {
  font-size: 0.875rem;
  line-height: 1.25rem;
  color: hsla(var(--foreground) / 0.8);
  padding-top: 0.5rem;
}

.combobox-max-height {
  max-height: 12rem;
  overflow-y: auto;
}

.combobox-group-label {
  font-size: 0.875rem;
  line-height: 1.25rem;
  color: hsla(var(--foreground) / 0.8);
  padding-top: 0.5rem;
}

[data-highlighted] {
  outline: 2px dotted hsla(var(--primary) / 1);
  background: hsla(var(--primary) / 0.08);
  border-radius: calc(var(--border-radius) / 2);
}

[data-disabled] {
  opacity: 0.6;
  background: hsl(var(--foreground) / 0.05);
}

.combobox-pill {
  display: inline-flex;
  align-items: center;
  gap: 0.25rem;
  margin-inline: 0.25rem;
  padding: 0.25rem 0.5rem;
  background-color: hsl(var(--muted));
  margin-block: 0.25rem;
}

.combobox-pill-container {
  padding-right: 44px;
  width: 100%;
}

.combobox-multiple {
  display: flex;
  flex-direction: column;
}

.combobox-multiple input {
  width: 100%;
}

.combobox-multiple .combobox-trigger {
  min-height: 48px;
  height: 100%;
  aspect-ratio: 1 / 1;
}

.combobox-clear {
  background: hsl(var(--secondary) / 0.08);
}

.combobox-control:focus-within .combobox-pill {
  background-color: hsl(var(--foreground) / 0.08);
}

.combobox-control:focus-within .combobox-clear {
  background: hsl(var(--secondary) / 0.25);
}

Some CSS variables are specific to the docs, feel free to plug in your own values or variables!

Keyboard Interaction

Key	Description
`Enter`	Selects a highlighted item when open. Toggles the selection of the highlighted item without closing the combobox if an item is already selected.
`ArrowDown`	Opens the combobox or moves focus down.
`ArrowUp`	Opens the combobox or moves focus up.
`Home`	When focus is on an item, moves focus to first item.
`End`	When focus is on an item, moves focus to last item.
`Esc`	Closes the combobox and moves focus to the trigger.
`Tab`	Moves focus to the next focusable element.

Multi Select

When in multi select mode, additional keyboard interactions are available.

Key	Description
`Enter`	Toggles the selection of the highlighted item without closing the combobox.

API

Data Attributes

Combobox.Root, Combobox.Trigger, and Combobox.Popover, all have data attributes that are used to track state.

Attribute	Description
`data-open`	If the popover is open (Boolean).
`data-closed`	If the popover is closed (Boolean).
`data-invalid`	If the combobox is invalid (Boolean).

Combobox.Item has the following data attributes:

Attribute	Description
`data-selected`	If the item is selected. (Boolean)
`data-highlighted`	If the item is highlighted. (Boolean)
`data-disabled`	If item is disabled. (Boolean)

Combobox.Root

Prop	Type	Description
`value`	`string`	Uncontrolled combobox value.
`bind:value`	`signal`	Controlled selected value, manages the selected item.
`filter`	`boolean`	Disables the default filter function when set to false.
`onChange$`	`QRL`	Function called when the selected value changes.
`bind:open`	`signal`	Controlled open state of the popover.
`onOpenChange$`	`QRL`	Function called when the popover opens or closes.
`loop`	`boolean`	Determines if focus cycles from the last item back to the first, or vice versa.
`placeholder`	`string`	Sets a placeholder instead of a selected value.
`multiple`	`boolean`	Enables multiple selections.
`bind:displayValue`	`signal`	Controlled display value, manages the display items.
`onInput$`	`QRL`	Function called when the user types in the input.

Combobox.Popover

Combobox.Popover is a wrapper of the Popover component, and has the same APIs.

Combobox.Item:

Prop	Type	Description
`value`	`string`	Give the combobox a value other than what is displayed in the item.
`disabled`	`boolean`	When true, the item is disabled.

Combobox

✨ Features

Roadmap

Building blocks

🎨 Anatomy

Why use a headless Combobox?

Passing data

Basic example

Mapping over data

Object example

Passing a distinct value

Handling selection changes

Component state

Uncontrolled / Initial value

Controlled / Reactive value

Programmatic changes

Disabled items

Dynamically adding items

Item indicators

Multiple selections

Remove items on backspace

Placeholder

CSR

Menu behavior

Custom Filter

Empty UI

Handling popover open/close

Reactive open state

Handling input changes

Reactive input value

Looping

Grouped Items

Scrolling

Advanced

Using Refs (experimental)

Forms

Validation

Example CSS

Keyboard Interaction

Multi Select

API

Data Attributes

Combobox.Root

Combobox.Popover

Combobox.Item: