Combobox
A text input with a list of suggestions that narrows as the user types.
Usage
import { Combobox } from '@leverui/components';
<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 onIntl.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.
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.
<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.
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 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.
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.
Store
An alternative way to control the combobox is to use the Combobox.RootProvider component and the useCombobox store hook.
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.
Links
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.
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.
-<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
fixedto avoid the combobox from being clipped by the dialog. - Set
hideWhenDetachedtotrueto hide the combobox when the trigger is scrolled out of view.
<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.
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
| Prop | Default | Type | Description |
|---|---|---|---|
collection (required) | — | ListCollection<T> | Collection that holds the items. |
composite | true | boolean | Combined with another composite widget, such as tabs. |
defaultValue | [] | string[] | Selected items on first render. Uncontrolled. |
inputBehavior | none | 'none' | 'autohighlight' | 'autocomplete' | How the input auto-completes as you type. |
loopFocus | true | boolean | Wrap keyboard navigation from the last item to the first. |
openOnChange | true | boolean | ((details: InputValueChangeDetails) => boolean) | Open the popup when the input text changes. |
openOnKeyPress | true | boolean | Open the popup on an arrow key. |
positioning | { placement: "bottom-start" } | PositioningOptions | Where the popup is placed. |
selectionBehavior | replace | 'clear' | 'replace' | 'preserve' | What happens to the input text on select. |
variant | outline | 'outline' | 'subtle' | 'flushed' | Combobox style. |
size | md | 'xs' | 'sm' | 'md' | 'lg' | Combobox size. |
as | div | Native tag | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the combobox's props. |
unstyled | — | boolean | Turn off the default styles. |
allowCustomValue | — | boolean | Allow a typed value that is not in the list. |
alwaysSubmitOnEnter | false | boolean | Submit the form on Enter, even with the popup open. |
autoFocus | — | boolean | Focus the input on first render. |
closeOnSelect | — | boolean | Close the popup when an item is selected. |
defaultHighlightedValue | — | string | Highlighted item on first render. Uncontrolled. |
defaultInputValue | `` | string | Input text on first render. Uncontrolled. |
defaultOpen | — | boolean | Open the popup on first render. Uncontrolled. |
disabled | — | boolean | Disable the combobox. |
disableLayer | — | boolean | Do not register as a dismissable layer. |
form | — | string | Form the combobox belongs to. |
highlightedValue | — | string | Highlighted item. Controlled. |
id | — | string | Unique ID for this combobox. |
ids | — | Element ID map | Your own ids for the combobox elements. |
immediate | — | boolean | Apply a present change right away. When false, wait a frame. |
inputValue | — | string | Input text. Controlled. |
invalid | — | boolean | Mark the combobox invalid. |
lazyMount | false | boolean | Render the popup content only once it first opens. |
multiple | — | boolean | Allow more than one selected item. Sets selectionBehavior to clear. Show the selected items in a separate container. |
name | — | string | name attribute of the input, for form submit. |
navigate | — | (details: NavigateDetails) => void | Function that navigates to the selected item. |
onExitComplete | — | VoidFunction | Called when the closing animation finishes. |
onFocusOutside | — | (event: FocusOutsideEvent) => void | Called when focus moves outside the combobox. |
onHighlightChange | — | (details: HighlightChangeDetails<T>) => void | Called when the pointer or keyboard highlights an item. |
onInputValueChange | — | (details: InputValueChangeDetails) => void | Called when the input text changes. |
onInteractOutside | — | (event: InteractOutsideEvent) => void | Called on an interaction outside the combobox. |
onOpenChange | — | (details: OpenChangeDetails) => void | Called when the popup opens or closes. |
onPointerDownOutside | — | (event: PointerDownOutsideEvent) => void | Called on a pointer press outside the combobox. |
onSelect | — | (details: SelectionDetails) => void | Called when an item is selected. |
onValueChange | — | (details: ValueChangeDetails<T>) => void | Called when the selected value changes. |
open | — | boolean | Whether the popup is open. Controlled. |
openOnClick | false | boolean | Open the popup when the input is first clicked. |
placeholder | — | string | Placeholder text of the input. |
present | — | boolean | Whether the popup content is present. Controlled. |
readOnly | — | boolean | Make it read-only. No edits, but still interactive. |
required | — | boolean | Mark the combobox required. |
scrollToIndexFn | — | (details: ScrollToIndexDetails) => void | Function that scrolls to the item at an index. |
skipAnimationOnMount | false | boolean | Skip the animation the first time the popup appears. |
translations | — | IntlTranslations | Localized text for accessible names and states. |
unmountOnExit | false | boolean | Remove the popup content from the page on close. |
value | — | string[] | Selected items. Controlled. |
Item
| Prop | Default | Type | Description |
|---|---|---|---|
as | div | Native tag | HTML tag to render. |
asChild | — | Solid render function | Render your own element with the item's props. |
item | — | any | Item to render. |
persistFocus | — | boolean | Keep 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.
.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