Reference

Every option

Every createAutocomplete option with its default: sources, requests, response mapping, caching, filtering, highlighting, timing, messages and callbacks.

Pass exactly one of source, endpoint or sections.

Source

Option Default Description
source none An array filtered locally, or (query, { signal, input }) => items (sync or async).
endpoint none URL, URL or (query, input) => URL.
queryParam 'q' Endpoint only. Query-string key; null when the endpoint function builds the complete URL.
requestInit {} Endpoint only. RequestInit or (query, input) => RequestInit for headers, credentials, method.
parseResponse response.json() Endpoint only. Parses the response before mapping.
mapResponse common arrays Endpoint only. (payload, response, query); the default reads a root array or suggestions, items or data.
filter label match Array only. (item, query) => boolean; the default matches every query word in the label.
normalize normalizeText Text comparison for the default filter and highlighting; ignores case and accents.
sections none Labelled groups searched in parallel: { id, label?, source, maxResults?, filter?, cache? }[].
cache true Function and endpoint sources. false, or { max: 50, ttl: 300000 } (queries, milliseconds).

Sections

Each section has a unique id (letters, digits, -, _), an optional label rendered as a group heading, and its own source (array or function). maxResults, filter and cache default to the instance options. Sections are searched in parallel and rendered in order; one failing section is dropped and reported through autocomplete:error, and the error state is shown only when every pending section fails and nothing else matched. When every section is an array, minLength defaults to 1 and debounce to 0.

The cache is keyed by the query alone. When an endpoint function or source also reads other state, such as a country select, call controller.clearCache() whenever that state changes.

Recent selections and forms

Option Default Description
recent none true or { store?, max?: 5, label?: 'Recent searches' }. Shows recent selections when the empty input gets focus or ArrowDown.
hiddenInput none A field name, or { name?, element?, getValue? }. Holds the selection’s id (or getValue) and empties when the text changes.

The default recent store uses localStorage under autocomplete:recent:<input id>, falls back to memory without an id or when storage is blocked, and dedupes by getId. Keep suggestions JSON-serializable, or pass your own store from createRecentStore(). The hidden input dispatches a bubbling change event when its value changes; a created one is removed on destroy(), an existing element is kept.

Rendering

Option Default Description
getId id, else the index Stable option id.
getLabel label, value, title, name Visible option text. Strings are used as they are.
getValue value, label, title, name Value written to the input on selection.
highlight true Wraps matching parts of the label in <mark data-autocomplete-highlight>.
renderStatus none (element, { state, query, error? }); replace the visible loading, empty or error copy. The live region keeps the message.
renderHeader none (element, { query, count, sections }); content above the listbox while results show.
renderFooter none (element, { query, count, sections }); content below the listbox while results show.
renderOption none (option, suggestion, { query, index, label, highlight }); customize without HTML.

Placement

Option Default Description
placement 'auto' 'auto' opens below and flips above when there is no room; 'bottom' or 'top' fix the side.
popover false Render the popup in the top layer with the Popover API, escaping overflow: hidden and stacking.
offset 4 Gap in CSS pixels between the input and a popover popup. Absolute popups use --autocomplete-offset.

The chosen side is written to data-placement. Without Popover API support, popover: true falls back to the absolute popup.

Timing and limits

Option Default Description
minLength 2, 1 for arrays Minimum query length before searching. 0 searches on focus.
debounce 250, 0 for arrays Delay in milliseconds after typing stops.
maxResults 8 Maximum rendered suggestions.
searchOnFocus true Search again on focus when the input already has a valid query.

Hooks and plugins

Option Default Description
beforeSearch none (query, input); return a new query, false to skip the search, or nothing to keep it.
transformSuggestions none (items, { query, section }); reorder, dedupe or enrich before maxResults applies.
beforeSelect none (item, input); return false to ignore the selection and keep the list open.
plugins [] { name, setup(controller) }[]; see the recipes.

Messages and callbacks

Option Default Description
messages English Partial { loading, empty, error, results }; each a string or ({ query, count }) => string.
onSelect none (suggestion, input) after a selection.
onError none (error, input) for source, request, parsing and mapping failures.

results is announced through the live region when suggestions load (default 1 result available / N results available). empty and error are shown and announced; loading is only shown.

Invalid numeric or cache options throw during initialization. Source, HTTP, parsing and mapping failures render the error state and dispatch autocomplete:error; sources and mapResponse must return an array. Failures are never cached.