Search select
Form-associated combobox with two modes, two trigger styles, multi-select chips, match highlighting, debounced search, and loading/empty/count states. A Lit Web Component migrated from the Angular esa-combobox.
Preview
<esa-combobox label="State" mode="select" placeholder="Pick a state"></esa-combobox>Modes
select uses a button trigger with in-panel search; autocomplete uses an input trigger. The text trigger style swaps the bordered field for a link-like control.
<esa-combobox label="Select mode" mode="select" placeholder="Pick a state"></esa-combobox>
<esa-combobox label="Autocomplete mode" mode="autocomplete" placeholder="Type to search"></esa-combobox>
<esa-combobox mode="select" trigger-style="text" placeholder="Filter by state"></esa-combobox>Sizes
<esa-combobox label="Extra small" size="xs"></esa-combobox>
<esa-combobox label="Small" size="sm"></esa-combobox>
<esa-combobox label="Medium" size="md"></esa-combobox>
<esa-combobox label="Large" size="lg"></esa-combobox>States
Multi-select renders chips. Loading, results-count, error, and disabled states are attribute-driven.
<esa-combobox label="States visited" mode="select" multiple placeholder="Add states"></esa-combobox>
<esa-combobox label="With results count" mode="select" results-count="50" help-text="Shows 'Displaying X of Y results'"></esa-combobox>
<esa-combobox label="Loading" mode="select" loading></esa-combobox>
<esa-combobox label="Error" error-text="Selection required"></esa-combobox>
<esa-combobox label="Disabled" disabled></esa-combobox>API
| Prop | Type | Default | Description |
|---|---|---|---|
mode | 'autocomplete' | 'select' | 'select' | 'select' = button trigger with in-panel search; 'autocomplete' = input trigger. Reflected. |
trigger-style | 'field' | 'text' | 'field' | 'field' = bordered control; 'text' = link-like trigger. |
options | { value, label, disabled? }[] | [] | Selectable options. Set as a property. |
multiple | boolean | false | Allow multiple selections with removable chips. |
size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Control size (reflected attribute). |
label | string | '' | Field label above the control. |
placeholder | string | 'Select...' | Placeholder for the trigger/input. |
disabled | boolean | false | Disables interaction (reflected attribute). |
required | boolean | false | Marks the field required. |
help-text | string | '' | Helper text below the control. |
error-text | string | '' | Error message; sets the error state when present. |
loading | boolean | false | Shows a spinner and "Searching..." state. |
debounce-ms | number | 300 | Debounce window for the search event. |
results-count | number | null | null | When set, renders "Displaying X of Y results". |
value | string | string[] | — | Property accessor. Single = string; multiple = string array. |
Events
| Event | Type | Default | Description |
|---|---|---|---|
change | CustomEvent<{ value: string | string[] }> | — | Fired on selection change. Composed and bubbles. |
search | CustomEvent<{ term: string }> | — | Debounced search term (300ms default), de-duplicated. Composed and bubbles. |
Accessibility
- Autocomplete input carries
role="combobox"witharia-expanded,aria-haspopup="listbox", andaria-autocomplete="list". - Panel is
role="listbox"; options arerole="option"witharia-selected. - Keyboard: ArrowUp/Down navigate, Enter selects, Escape/Tab close. Outside-click closes.
- Matched substrings are wrapped in
<mark>for visible highlight. - Form-associated via
ElementInternals— value submits with the enclosing form.
Tokens
--color-background-field·--form-text-color·--form-border-color/--form-border-color-focus/--form-error-border-color- Sizing reads
--spacing-*directly (the--form-height/padding/radius/font-size-*hooks were removed upstream, 2026-08) --color-background-elevation-raised·--color-background-elevation-sunken·--color-background-overlay-active·--color-background-brand/--color-background-brand-hover--color-background-utility-warning-subtle(highlight) ·--focus-ring-color·--z-dropdown·--elevation-3·--radius-full