Combobox

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.

Inherited wc import '@esa/ecology/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.