Combobox#

An editable text input over a filtered listbox: the WAI-ARIA editable combobox pattern. Focus stays in a real <input role="combobox">, the highlighted option is conveyed through aria-activedescendant, and the items are JSX children you filter yourself — zero registers, highlights and selects them, and prunes a highlight whose item unmounts mid-typing.

Import#

import { Combobox } from '@sigx/zero/combobox';

Combobox is a compound: Combobox.Root, Combobox.Control, Combobox.Input, Combobox.Trigger, Combobox.Popup, Combobox.Group, Combobox.GroupLabel, Combobox.Item, Combobox.Empty. It is also re-exported from the @sigx/zero root, together with comboboxAnatomy, useComboboxContext and useComboboxGroupContext.

Usage#

import { component } from 'sigx';
import { Combobox } from '@sigx/zero/combobox';

const fruits = ['Apple', 'Banana', 'Cherry', 'Lime'];

const FruitSearch = component(({ signal }) => {
    const state = signal({ fruit: '', query: '' });
    const matches = () => fruits.filter((f) => f.toLowerCase().includes(state.query.toLowerCase()));

    return () => (
        <Combobox.Root model={() => state.fruit} model:inputValue={() => state.query} name="fruit">
            <Combobox.Control>
                <Combobox.Input placeholder="Search fruit…" />
                <Combobox.Trigger />
            </Combobox.Control>
            <Combobox.Popup>
                {matches().map((f) => (
                    <Combobox.Item value={f} key={f}>{f}</Combobox.Item>
                ))}
                {matches().length === 0 ? <Combobox.Empty>No fruit found</Combobox.Empty> : null}
            </Combobox.Popup>
        </Combobox.Root>
    );
});

Filtering is yours: bind model:inputValue (or listen to inputValueChange), render only the items that match, and render Combobox.Empty yourself when nothing does. Zero owns no emptiness logic. Selecting an item writes its value to the model and fills the input with the item's text; an external value write (a form reset, server data) reflects into the input once the matching item is known.

Named models#

Combobox has three pieces of controllable state, each a model:

The unnamed model is the essential value — what the hidden input posts. Every additional piece of state is a named model, bound as model:<name> in JSX, with the same default<Name> + <name>Change companions. Any of the three may be left uncontrolled. See Models.

Option groups#

<Combobox.Popup>
    <Combobox.Group>
        <Combobox.GroupLabel>Citrus</Combobox.GroupLabel>
        <Combobox.Item value="lime">Lime</Combobox.Item>
    </Combobox.Group>
</Combobox.Popup>

Combobox.Group renders role="group" inside the listbox, named by its GroupLabel through aria-labelledby while one is rendered — exactly as in Select. Your filter renders or omits whole groups.

The options sugar#

<Field.Root>
    <Field.Label>Fruit</Field.Label>
    <Combobox.Root
        model={() => state.fruit}
        model:inputValue={() => state.query}
        options={matches().map((f) => ({ value: f }))}
    />
</Field.Root>

With no slot children, options renders the default composition — Control(Input, Trigger) and a Popup with an Item per entry and a Group + GroupLabel per distinct group in first-appearance order, label defaulting to value — through the same anatomy. It is rendering sugar only: filtering stays yours, so bind model:inputValue and pass an already-narrowed array. Slot children win entirely when both are given. Name an options-driven Combobox through a Field — its label lands on the generated input via the control id.

Tags, and values the list does not hold#

<Field.Root>
    <Field.Label>Tools</Field.Label>
    <Combobox.Root
        items={tools}
        multiple
        allowCustom
        defaultValue={['search', 'shell']}
        name="tools"
        placeholder="Add a tool…"
        emptyText="Press Enter to add it"
    />
</Field.Root>

Under multiple, the data expansion (a root with items and no children) renders one Combobox.Tag per chosen value, in selection order, in the control before the input. A tag's default content is a Combobox.TagLabel and a Combobox.TagRemove — a real <button> in the tab order, named Remove <label>, which hands focus back to the input. Backspace on an empty input removes the last value, so the remove buttons are how a keyboard user reaches any other tag. A tag keeps its label after a consumer-filtered item unmounts.

The root's tag slot replaces a tag's content — for a per-tag control such as a mode select. It receives { value, label, item }, where item is the data item (undefined for a custom value):

<Combobox.Root items={tools} multiple slots={{
    tag: ({ value, label }) => (
        <>
            <Combobox.TagLabel />
            <ModePicker tool={value} />
            <Combobox.TagRemove label={`Remove ${label}`} />
        </>
    ),
}} />

A hand-written root places the tags itself: Combobox.Tags inside Combobox.Control renders one Combobox.Tag value={key} per chosen value (its default slot takes the same { value, label, item }), or write individual Combobox.Tags.

allowCustom commits the typed text on Enter while no option is highlighted. A chosen value, or an option whose label the text names (case-insensitively), wins; otherwise the trimmed text itself becomes the value. Under multiple it adds a tag and clears the input; in single mode it sets the value and closes. A custom value posts through the hidden <select> like any other — data mode posts chosen values the items do not hold. The overloads type allowCustom only for a string model: hand-written items, string items, or a string itemValue.

Anatomy#

Every part carries data-scope="combobox" and data-part="<part>". The root is the carrier part for the variant axes. The input carries no data-placeholder flag — it is a real text input, so :placeholder-shown is the selector. The popup is popover="manual" plus zero's dismiss layer: native auto light dismiss would close the list on a caret click in the input, so dismissal is outside-press only, with Escape owned by the input's key handler. It is positioned against the control through the positioning behavior. See The anatomy contract.

Props#

Combobox.Root#

Field context (disabled, invalid, required, aria-describedby, the control id on the input) is merged with the props.

Combobox.Input#

Combobox.Trigger#

The default content is a chevron glyph. A click toggles the popup and returns focus to the input.

Combobox.Control, Combobox.Popup, Combobox.Group, Combobox.GroupLabel, Combobox.Empty#

Only class.

Combobox.Tags, Combobox.Tag, Combobox.TagLabel, Combobox.TagRemove#

On Combobox.Root, multiple (boolean) holds an array of values, and allowCustom (boolean) commits free text on Enter as described above.

Combobox.Item#

Keyboard#

Focus stays in the input throughout; options never receive focus, and there is no typeahead — typing is the filter.

In the shipped design systems#

Both @sigx/zero-basic and @sigx/zero-daisyui wire color (all eight recommended roles) and size (xs–xl) on combobox, so <Combobox.Root color="primary" size="sm"> is styled in both. Neither wires a variant on the scope; under a design system's /register import the prop is therefore absent. Both draw the well and the focus ring on control, style the popup's open / closed transition and the highlighted / selected item flags, and give empty its muted text. See Typed vocabulary.

Related#

Select for a select-only listbox, Field for labelling.