<ui-combobox>

1. mode="list" — filtered listbox

The default. Typing filters a listbox of suggestions. Free-form values are allowed on Enter.

2. mode="inline" — ghost suffix only

No listbox. The top match is shown as a gray suffix after the caret; Tab or Right accepts it.

3. mode="both" — listbox + ghost + arrow-nav preview

The full APG pattern. Type to filter; arrow keys preview each match in the input (Google-style); wrap past the last/first item restores your typed query. Enter/Tab commits.

4. mode="none" — editable select

Always shows the complete, unfiltered list. Use this for a free-text field with suggested values. Focusing the field opens the list without typing.

5. Async source with simulated latency

Shorter queries deliberately take longer in this demo, simulating a broad search such as s taking longer than spock. Normal typing can therefore produce responses out of order. This exercises stale-response checks, AbortSignal cancellation and the rule that existing results remain visible until replacements arrive. The host's data-loading="true" attribute dims existing options and can be used for additional loading styles.

6. Custom render_item — email autocomplete (with browser autofill)

Each option shows a name above an email address, as used by the workflow invite form. The child <input type="email" autocomplete="email"> retains browser email autofill while the combobox supplies team-member suggestions. The combobox suppresses its empty-state row when there is no query, reducing interference with the browser's autofill popup.

7. Error handling

Type a query containing "fail" to see the error row. The next successful query clears it.

8. Rich decorated items + prefix decoration

Consumer-controlled decoration: the listbox renders each option as flag + name + dialing code via .render_item, and a flag prefix inside the group tracks both arrow-nav preview and committed selection. The wrapper is the shared .input-group pattern, and the raw attribute strips the combobox's own chrome so the group owns the border and focus ring.

Two hooks are wired:

• input — fires on every user-driven value change: keystrokes and arrow-nav through options (which rewrites the input value in mode="both"). Read event.target.value and preview the flag for the current text.
• change fires when a value is committed through Enter, Tab, a click, ArrowRight acceptance or clearing. Use it to update decorations for the committed selection.

Related: the Open UI customizable select rich-content example and <x-select> show the same pattern for a closed select.

9. Suffix search indicator

Async source with a live-region suffix that shows a spinner while loading and a result-state icon afterwards. The group drives state via group.dataset.state, which the shared .input-group state styles pick up (flux → warning tint while loading; the .suffix.state slot recolors to match). The combobox carries raw so the group owns the border.

Keep source() limited to returning items or throwing an error. Update the suffix in listeners for ui-combobox-fetch, ui-combobox-response, ui-combobox-error and ui-combobox-revert. These events also cover cached queries and track the latest request. Each handler checks cb.value so a late response cannot restore an indicator after the input was cleared. An input listener handles an empty field immediately; clear() emits ui-combobox-revert itself.

10. Form participation

The name attribute creates a hidden field; the value is sent with the form on submit.

11. chips — single-token closed-list picker

Only values from the list are valid: the committed member becomes a removable chip and the typed text is only ever a query. The chip is one unit — Backspace in the empty input removes it whole, typing with it present replaces it, and its × (or Delete on the focused chip) removes it. Free-form Enter commits nothing. An author-supplied required is mirrored onto the selection, so native form validation blocks until a member is picked.

Chips do not support inline text completion. With mode="inline" or "both", the component uses list and logs a warning. Inline completion commits text, while a chip selects an item that must be removed or replaced as a whole. Supporting both would require a design for item selection and restoration of the typed query; changing the attribute alone cannot provide it.

12. multiple — tag input

Any number of chips, each removable. With min-chars="0" the list stays open after each pick and already-selected items leave it (they resurface when removed). One hidden field per chip, so the form submits like a checkbox group — read with FormData.getAll(name). ← at the start of the input steps into the chip row; ←/→ traverse it.

How it behaves

Which item the inline suggestion shows

The ghost suffix previews what Tab, →, End or Enter at the end of the input would commit. It comes from an item whose format(item) starts with the typed text, compared without regard to case, so lowercase typing still matches title-case items. Diacritics still count: typed te does not match Téa.

After arrow navigation only the highlighted item can supply the suggestion; showing another item's suffix would contradict the highlight. Otherwise the first rendered item that still matches supplies it, not only the first item. For example, typed Lov keeps Lovech suggested from the previous results while the new query is still loading. Disabled items never supply it, because none of those keys can commit them.

While the user types, the input keeps exactly what they typed, in their own casing; the ghost adds the rest of the canonical text. Typed PAR against Paris therefore reads PARis until the commit writes format(item).

Arrow-key preview

The first ↓ or ↑ saves the typed text. Each option the arrow keys highlight then replaces the input value with format(item), so the user sees what Enter would commit. The component fires input on the host for each preview but runs no new search. Moving past either end of the list, Esc, or leaving the field without committing restores the saved text. A run of disabled options at an end wraps the same way, because nothing further can be reached in that direction.

A highlight from the pointer, or the automatic highlight of the option matching the input when the list reopens, only marks the option. It saves nothing and changes nothing in the input, so Esc then just closes the list. The next arrow key moves on from that option and starts the preview.

Requests and stale responses

Each typed query passes through to_query, and the promise source() returns is memoized under that canonical query, for up to 50 queries with the oldest dropped first. A request that is not memoized aborts every older request still running. A response older than the one already rendered is dropped, and so is an older error. A rejected promise is removed from the memo, aborts included, so the same query calls source() again next time instead of staying in the loading state. An AbortError is otherwise silent; any other error renders an error row and is announced through the component's live region, because the listbox itself is not a live region.

When the list opens

A request opens the list immediately, so a slow network still gives feedback at once; existing options stay in place. data-loading="true" and, in an otherwise empty list, a … row appear only after 300 ms, so fast responses cause no flash. Focusing the input with min-chars="0" prefetches, so the list has content the first time it opens.

An empty query with no results closes the list rather than showing the empty row: "No matches" for nothing typed means nothing, and on an autocomplete="email" field it would cover the browser's autofill popup.

Accessibility

• The input carries role="combobox", aria-autocomplete, aria-expanded, aria-controls, aria-activedescendant.
• The listbox is a <ul role="listbox"> carrying popover="manual", labelled by the input; options are <li role="option">.
• Status rows (empty / loading / error) carry role="option" aria-disabled="true" so they appear in the accessibility tree and are announced. They are not keyboard-navigable — the component skips elements without data-opt-id. For richer announcements (spinner, result count, error icon) use the pipeline events with a consumer-owned aria-live region — see §9 (Suffix search indicator).
• An item disabled by option_disabled has aria-disabled="true" and keeps its data-opt-id, which indexes the rendered item list. Removing that id would misalign later options with their items. The highlight check prevents navigation to it. It remains visible to assistive technology; include the reason in render_item so the option's accessible name explains why it is unavailable.
• DOM focus never leaves the input — highlight moves via aria-activedescendant (APG virtual focus).
• Keyboard: ↓/↑ navigate and preview in the input (Google-style); wrap past the ends restores the typed query. Enter commits; Esc restores typed (arrow-nav) then closes then clears; Tab commits the highlighted item or accepts the ghost at end; Alt+↓/Alt+↑ open/close without moving highlight.
• Chips are native <button>s in the tab order — the whole chip is its remove button, with an accessible name from chip_remove_label that contains the visible label (WCAG 2.5.3 Label in Name); the × glyph is aria-hidden. role="combobox" stays on the always-focusable input. Add/remove is announced through the component's polite live region (chip_announcement). Keyboard: Backspace in the empty input removes the last chip; ← at caret 0 enters the chip row; ←/→ traverse chips; Delete/Backspace on a focused chip removes it (focus moves to the next chip, else previous, else the input); Esc clears the query text but never chips.
• The input comes first in DOM order. Flex order places chips visually before it. This keeps a wrapping <label>, as used by .input-group, associated with the input: a label targets its first labelable descendant. If a chip came first, clicking the field or selecting an option could activate that chip's remove button. Tab reaches the input first; chips follow in tab order and can also be reached with ←.

Handling Escape

Escape can restore the typed query after arrow navigation, close the list or clear the input. In chips mode it clears only the query. When it handles any of these, the component cancels the event without stopping propagation. Ancestor handlers must check e.defaultPrevented. Checking whether a list is open is insufficient: restoring a query leaves it open, and clearing an input does not require an open list. The combobox's own keydown handler likewise ignores events that another handler has already cancelled.

When the list is closed and there is no tentative query or input to clear, the combobox neither cancels nor stops Escape. The enclosing dialog or form can then handle it. The list uses popover="manual" so a browser close watcher cannot act independently of this handler, as it would with auto.

Check e.defaultPrevented to distinguish an Escape event the combobox handled from one it left alone. Menus and notification panels also cancel without stopping propagation. A popover additionally stops propagation, so its handled Escape events do not reach bubbling ancestor listeners.

A select also handles Escape only when it has something to close. Its picker uses popover="auto", however, so cancellation must also prevent the browser's close watcher from closing an enclosing overlay after the picker has closed. The combobox uses popover="manual" and has no browser close watcher.

Labeling

The inner <input> carries role="combobox", so its accessible name is what screen readers announce. Three patterns, in preference order:

1. Visible <label for> — preferred. Give the author-supplied input an explicit id and point a <label> at it. The label stays visible when the user types, which helps everyone.
2. Visually-hidden <label for> — when a visible label would be redundant (e.g. a search field whose purpose is obvious from surrounding context). The label is still in the DOM and announced by screen readers.
3. aria-label on the input — last resort, for cases like a decorated .input-group where adding a separate label element would break the layout. Put aria-label directly on the author-supplied <input>.

Do not rely on placeholder as the accessible name. Placeholders vanish once the user types, and they cause the listbox's own accessible name (which mirrors the input) to become the typed query rather than the field purpose.

Ghost-layer a11y trade-off

The inline completion is rendered by a sibling DOM mirror (marked aria-hidden), not by mutating input.value. This avoids async-input-event races on mobile virtual keyboards and during IME composition, at the cost of losing the traditional screen-reader channel for inline autocomplete. Arrow-nav, however, DOES update input.value programmatically (Google-style preview); this surfaces the canonical option to assistive tech the moment the user arrows to it.

See also

• <x-select> — when you need a closed select with custom styling but no free-text or async options.
• Input groups (.input-group) — how [raw] mode pairs with prefix/suffix decoration and a wrapper-owned border.
• Source: ui-combobox.mjs
• Full test suite
• W3C APG — Combobox pattern — the ARIA authoring-practices spec this component implements.