Combobox

Single-value picker with a searchable text input, built on Base UI Combobox. As the user types, the option list is filtered (accent-insensitive); options can also be loaded asynchronously.

When to use

Reach for Combobox when the user picks one value from a list and should be able to filter by typing (or the options come from a server).

• Don't need search? Use Select.
• Need to pick multiple values? Use MultiCombobox.

Use @uxf/ui/combobox for a controlled combobox outside a form. Inside a @uxf/form form, use @uxf/form/combobox instead — it registers the field with react-hook-form and derives isInvalid / helperText from validation. This @uxf/ui component is the controlled primitive the form twin wraps.

Usage

import { Combobox, ComboboxOption, ComboboxValue } from "@uxf/ui/combobox";
import { useState } from "react";

const options: ComboboxOption[] = [
    { id: "one", label: "Option one" },
    { id: "two", label: "Option two", disabled: true },
    { id: "three", label: "Option three" },
];

function Example() {
    const [value, setValue] = useState<ComboboxValue | null>(null);

    return (
        <Combobox
            isClearable
            label="Choose an option"
            name="example"
            onChange={setValue}
            options={options}
            placeholder="Search..."
            value={value}
        />
    );
}

Async options — pass loadOptions instead of (or alongside) options; the returned promise supplies the list and local filtering is skipped:

<Combobox
    label="Country"
    loadOptions={(query, { signal }) => fetchCountries(query, { signal })}
    name="country"
    onChange={setValue}
    placeholder="Search country..."
    value={value}
/>

Content below the options — dropdownEndContent, e.g. a button that adds an item the search did not find. The function form gets args.close(); static content leaves the dropdown open:

<Combobox
    dropdownEndContent={(args) => (
        <Button
            isFullWidth
            onClick={() => {
                args.close();
                openAddCountryModal();
            }}
            variant="text"
        >
            Add a new country
        </Button>
    )}
    label="Country"
    loadOptions={(query, { signal }) => fetchCountries(query, { signal })}
    name="country"
    onChange={setValue}
    value={value}
/>

value is the selected option object (ComboboxValue, i.e. { id, label }) or null, and onChange receives that whole object — not just the id.

Exports: Combobox and the types ComboboxProps, ComboboxOption, ComboboxValue, ComboboxValueId, ComboboxTypeRef.

Props

ComboboxProps<Id = ComboboxValueId, Option = ComboboxOption<Id>, Value = Option> extends FormControlProps<Value | null> and Clearable. ComboboxValueId is number | string; ComboboxValue is { id: Id; label: string }; ComboboxOption adds disabled?: boolean.

Layout, dropdown, and ref props: className, style, form, leftAddon, rightAddon, leftElement, rightElement, inputArrow, dropdownClassName, dropdownEndContent, dropdownMatchesInputWidth (default true), dropdownMaxHeight (default 240), dropdownPlacement (default "bottom"), dropdownStrategy, inputRef, inputGroupRef, inputWrapperRef.

Variants & states

• Search: typing filters options locally by label (accent-insensitive via slugify). With loadOptions, filtering is delegated to the loader (debounced ~200 ms).
• Sizes: small, default, large (via size).
• Invalid: set isInvalid; combine with helperText to show an error message.
• Disabled / read-only: isDisabled blocks interaction; isReadOnly keeps focus but prevents changes.
• Clearable: with isClearable, a remove button appears once a value is selected (unless disabled/read-only).
• Empty states: distinct messages for empty query, no options, and no match (see props above).
• Content below the options: dropdownEndContent pins content (typically an "add a new item" button) below the options. It stays visible while the list scrolls and when nothing matches, fits inside dropdownMaxHeight together with the list, and is not part of the arrow-key navigation. Static content (ReactNode) leaves the dropdown open; the function form (args) => ReactNode gets args.close(), which closes the dropdown without changing the value.

Requirements

The component composes the input, label, dropdown, form-component, and icon primitives, so import all of their stylesheets once in your global CSS:

@import url("@uxf/ui/css/icon.css");
@import url("@uxf/ui/css/dropdown.css");
@import url("@uxf/ui/css/label.css");
@import url("@uxf/ui/css/form-component.css");
@import url("@uxf/ui/css/input-basic.css");
@import url("@uxf/ui/css/input.css");
@import url("@uxf/ui/css/combobox.css");

Also requires the global @uxf/ui token layer, set up once per app — see @uxf/ui setup.