Combobox

A text input with a list of suggestions that narrows as the user types.

Usage

Code
import { Combobox } from '@leverui/components';
Code
<Combobox.Root>
  <Combobox.Label />

  <Combobox.Control>
    <Combobox.Input />
    <Combobox.IndicatorGroup>
      <Combobox.ClearTrigger />
      <Combobox.Trigger />
    </Combobox.IndicatorGroup>
  </Combobox.Control>

  <Combobox.Positioner>
    <Combobox.Content>
      <Combobox.Empty />
      <Combobox.List>
        <Combobox.Item />

        <Combobox.ItemGroup>
          <Combobox.ItemGroupLabel />
          <Combobox.Item />
        </Combobox.ItemGroup>
      </Combobox.List>
    </Combobox.Content>
  </Combobox.Positioner>
</Combobox.Root>
  • useListCollection: holds the items, with methods to filter and change the list.

  • useFilter: matching logic for filtering, built on Intl.Collator.

Keep the popup inside the same Combobox.Root in your code, even when Portal moves its DOM. Roles and form attributes are set for you. Give an icon-only trigger an accessible name.

Examples

Basic

The basic combobox provides a searchable dropdown with single selection.

Sizes

Pass the size prop to the Combobox.Root to change the size of the combobox.

Variants

Pass the variant prop to the Combobox.Root to change the appearance of the combobox.

Multiple

Pass the multiple prop to the Combobox.Root to enable multiple selection. This allows users to select multiple items from the list.

When this is set, the combobox will always clear the input value when an item is selected.

Async Loading

Here's an example of loading the collection asynchronously as users type, perfect for API-driven search interfaces.

Highlight Matching Text

Here's an example of composing the Combobox.Item and Highlight components to highlight matching text in search results.

Open on Click

Use the openOnClick prop to open the combobox when the user clicks on the input.

Custom Objects

By default, the combobox collection expects an array of objects with label and value properties. In some cases, you may need to deal with custom objects.

Use the itemToString and itemToValue props to map the custom object to the required interface.

Code
const items = [
  { country: 'United States', code: 'US', flag: '🇺🇸' },
  { country: 'Canada', code: 'CA', flag: '🇨🇦' },
  { country: 'Australia', code: 'AU', flag: '🇦🇺' },
  // ...
];

const matcher = useFilter({ sensitivity: 'base' });

const { collection } = useListCollection({
  initialItems: items,
  itemToString: (item) => item.country,
  itemToValue: (item) => item.code,
  filter: (text, query) => matcher().contains(text, query),
});

Minimum Characters

Use the openOnChange prop to set a minimum number of characters before filtering the list.

Code
<Combobox.Root openOnChange={(details) => details.inputValue.length > 2} />

Field

Compose the Combobox component with the Field component to wrap the combobox in a form field. Useful for form layouts.

The framework you use most

Form + Custom Object

When working with custom objects in forms, you often need to submit the programmatic value rather than the display value. This example shows how to combine custom object mapping with form submission using a hidden input.

The form sends the country code, such as "US", not the country name.

The key is using itemToValue to define what gets submitted, while itemToString controls what users see. A hidden input captures the programmatic value for form submission.

In this example, users see "🇺🇸 United States" but the form submits "US".

Hook Form

This example demonstrates how to integrate the Combobox with a form, holding the value in a Solid signal. The form automatically receives the item's value property without needing a hidden input.

Users see "React" but the form receives "react".

Disabled State

Pass the disabled prop to the Combobox.Root to disable the entire combobox.

Disabled Item

Disable specific items in the dropdown, add the disabled prop to the collection item.

Code
const items = [
  { label: 'Item 1', value: 'item-1', disabled: true },
  { label: 'Item 2', value: 'item-2' },
];

const { collection } = useListCollection({
  initialItems: items,
  // ...
});

Input Group

Combine with InputGroup to add icons or other elements.

Invalid

Pass the invalid prop to the Combobox.Root to show the error state.

Controlled Value

Use the value and onValueChange props to control the combobox's value programmatically.

Selected:
N/A

Store

An alternative way to control the combobox is to use the Combobox.RootProvider component and the useCombobox store hook.

Code
import { Combobox, useCombobox } from '@leverui/components';

/** Pass a caller-owned machine to the provider. */
function Demo() {
  const combobox = useCombobox();

  return <Combobox.RootProvider value={combobox}>{/* ... */}</Combobox.RootProvider>;
}

This way you can access the combobox state and methods from outside the combobox.

Controlled Open

Use the open and onOpenChange props to control the combobox's open state programmatically.

Limit Large Datasets

The recommended way of managing large lists is to use the limit property on the useListCollection hook. This will limit the number of rendered items in the DOM to improve performance.

Virtualization

Alternatively, you can virtualize large datasets with TanStack Virtual. Its Solid adapter targets Solid 1, so the example uses a small Solid 2 binding over @tanstack/virtual-core.

Use the asChild prop to render the combobox items as links.

For custom router links, you can customize the navigate prop on the Combobox.Root component.

Here's an example of using Solid Router.

Code
import { Combobox } from '@leverui/components';
import { useNavigate } from '@solidjs/router';

/** Route selected links through the application router. */
function Demo() {
  const navigate = useNavigate();
  return (
    <Combobox.Root
      navigate={({ href }) => {
        navigate(href);
      }}
    >
      {/* ... */}
    </Combobox.Root>
  );
}

Rehydrate Value

In some cases, where a combobox has a defaultValue but the collection is not loaded yet, here's an example of how to rehydrate the value and populate the input value.

Custom Item

Customize the appearance of items in the dropdown with your own components.

Custom Filter

Here's an example of a custom filter that matches multiple properties of an item.

Custom Animation

To customize the animation of the combobox, set the --leverui-combobox-content-open-animation and --leverui-combobox-content-closed-animation variables on the Combobox.Content component.

Open From Dialog

To use the combobox within a dialog or popover component, avoid wrapping the Combobox.Positioner within the Portal.

Code
-<Portal>
  <Combobox.Positioner>
    <Combobox.Content>
      <Combobox.List>
        {/* ... */}
      </Combobox.List>
    </Combobox.Content>
  </Combobox.Positioner>
-</Portal>

If you use a Dialog and have set scrollBehavior="inside", you need to:

  • Set the combobox positioning to fixed to avoid the combobox from being clipped by the dialog.
  • Set hideWhenDetached to true to hide the combobox when the trigger is scrolled out of view.
Code
<Combobox.Root positioning={{ strategy: 'fixed', hideWhenDetached: true }}>
  {/* ... */}
</Combobox.Root>

Creatable

Here's an example of how to allow users to create new options by typing values that don't exist in the list. It uses the useCombobox and Combobox.RootProvider components for smoother integration and management.

Note: This example is not fully tested. Feel free to use it as a starting point and improve it according to your needs.

Guides

Controlling the value

Pass value and onValueChange. If you change the value from outside while the list is filtered, the input can show up empty. Call reset() first.

Code
const { collection, filter, reset } = useListCollection({
  initialItems: items,
  filter: (text, query) => matcher().contains(text, query),
});

// When changing value externally, reset the filter first
function setValueWithReset(next: string[]) {
  reset();
  setValue(next);
}

Fixed list: pass the result of createListCollection. Filter as people type: call useListCollection in a Solid component, pass collection() to Root, and call filter(details.inputValue) from onInputValueChange. The items in the collection and the Item parts you render must match.

Put the items inside List. It has the listbox role and handles keyboard focus. Content is the popup around it and can hold a header, a footer, or a search input. Place Empty and Status next to List inside Content. Empty is a polite status region that shows its children only while the collection is empty. Status announces loading or error messages without adding them to the options.

To own the state, call Combobox.useCombobox() in the body of a Solid component and pass the accessor it returns to Combobox.RootProvider. Combobox.PropsProvider takes default props as an object or an accessor. A prop on a combobox wins. Combobox.Context and Combobox.ItemContext give the current state of the combobox and of one item.

Props

Root

PropDefaultTypeDescription
collection (required)—ListCollection<T>Collection that holds the items.
compositetruebooleanCombined with another composite widget, such as tabs.
defaultValue[]string[]Selected items on first render. Uncontrolled.
inputBehaviornone'none' | 'autohighlight' | 'autocomplete'How the input auto-completes as you type.
loopFocustruebooleanWrap keyboard navigation from the last item to the first.
openOnChangetrueboolean | ((details: InputValueChangeDetails) => boolean)Open the popup when the input text changes.
openOnKeyPresstruebooleanOpen the popup on an arrow key.
positioning{ placement: "bottom-start" }PositioningOptionsWhere the popup is placed.
selectionBehaviorreplace'clear' | 'replace' | 'preserve'What happens to the input text on select.
variantoutline'outline' | 'subtle' | 'flushed'Combobox style.
sizemd'xs' | 'sm' | 'md' | 'lg'Combobox size.
asdivNative tagHTML tag to render.
asChild—Solid render functionRender your own element with the combobox's props.
unstyled—booleanTurn off the default styles.
allowCustomValue—booleanAllow a typed value that is not in the list.
alwaysSubmitOnEnterfalsebooleanSubmit the form on Enter, even with the popup open.
autoFocus—booleanFocus the input on first render.
closeOnSelect—booleanClose the popup when an item is selected.
defaultHighlightedValue—stringHighlighted item on first render. Uncontrolled.
defaultInputValue``stringInput text on first render. Uncontrolled.
defaultOpen—booleanOpen the popup on first render. Uncontrolled.
disabled—booleanDisable the combobox.
disableLayer—booleanDo not register as a dismissable layer.
form—stringForm the combobox belongs to.
highlightedValue—stringHighlighted item. Controlled.
id—stringUnique ID for this combobox.
ids—Element ID mapYour own ids for the combobox elements.
immediate—booleanApply a present change right away. When false, wait a frame.
inputValue—stringInput text. Controlled.
invalid—booleanMark the combobox invalid.
lazyMountfalsebooleanRender the popup content only once it first opens.
multiple—booleanAllow more than one selected item. Sets selectionBehavior to clear. Show the selected items in a separate container.
name—stringname attribute of the input, for form submit.
navigate—(details: NavigateDetails) => voidFunction that navigates to the selected item.
onExitComplete—VoidFunctionCalled when the closing animation finishes.
onFocusOutside—(event: FocusOutsideEvent) => voidCalled when focus moves outside the combobox.
onHighlightChange—(details: HighlightChangeDetails<T>) => voidCalled when the pointer or keyboard highlights an item.
onInputValueChange—(details: InputValueChangeDetails) => voidCalled when the input text changes.
onInteractOutside—(event: InteractOutsideEvent) => voidCalled on an interaction outside the combobox.
onOpenChange—(details: OpenChangeDetails) => voidCalled when the popup opens or closes.
onPointerDownOutside—(event: PointerDownOutsideEvent) => voidCalled on a pointer press outside the combobox.
onSelect—(details: SelectionDetails) => voidCalled when an item is selected.
onValueChange—(details: ValueChangeDetails<T>) => voidCalled when the selected value changes.
open—booleanWhether the popup is open. Controlled.
openOnClickfalsebooleanOpen the popup when the input is first clicked.
placeholder—stringPlaceholder text of the input.
present—booleanWhether the popup content is present. Controlled.
readOnly—booleanMake it read-only. No edits, but still interactive.
required—booleanMark the combobox required.
scrollToIndexFn—(details: ScrollToIndexDetails) => voidFunction that scrolls to the item at an index.
skipAnimationOnMountfalsebooleanSkip the animation the first time the popup appears.
translations—IntlTranslationsLocalized text for accessible names and states.
unmountOnExitfalsebooleanRemove the popup content from the page on close.
value—string[]Selected items. Controlled.

Item

PropDefaultTypeDescription
asdivNative tagHTML tag to render.
asChild—Solid render functionRender your own element with the item's props.
item—anyItem to render.
persistFocus—booleanKeep the highlight when the pointer leaves the item.

Trigger, ClearTrigger, and ItemIndicator show a default icon without children. The parts the combobox controls accept asChild and as. Keep the props you are given on your element, or keyboard and accessibility behavior breaks.

Customize with CSS

Import @leverui/components/styles.css, then set --leverui-combobox-* variables on :root, a theme wrapper, or a single Combobox. The root and its parts have data-size, data-variant, and interaction state attributes. Content moved by a portal gets the same size and variant attributes. Each part has a stable class.

Code
.leverui-combobox__input {
  border-radius: 0.75rem;
}

Each part accepts class, style, and unstyled.

Explorer

Click a part name to highlight it in the preview.

Component Anatomy

Hover to highlight, click to select parts