- Docs
- API reference
API reference
createAutocomplete, the controller, state and plugins, the headless search and helpers, the registry, declarative mount and every event.
createAutocomplete(target, options)
target is an HTMLInputElement or a selector. Returns an AutocompleteController<T>. autocomplete is an alias. Throws a TypeError when the target is not an input, when not exactly one of source, endpoint and sections is given, or when an option is invalid.
Controller
| Member | Description |
|---|---|
element |
The managed input. |
popupElement |
The positioned container inserted after the input. |
listElement |
The generated listbox inside the popup. |
statusElement |
The visible loading, empty or error message inside the popup. |
liveElement |
The visually hidden polite live region after the popup. |
hiddenElement |
The synced hidden input, or null without hiddenInput. |
recent |
The recent selections store, or null without recent. |
options |
The options object you passed. |
search(query?) |
Runs a search now, without debounce. |
close() |
Closes the list and cancels the pending or in-flight search. |
clear() |
Clears the input, selection, results and pending work. |
cancel() |
Cancels the debounce timer and aborts the active request. |
clearCache() |
Forgets every cached query. |
getSelected() |
The original selected suggestion, or null. |
setValue(item) |
Selects item (or null) without events: input text, hidden input and state. For edit forms. |
getState() |
The current AutocompleteState snapshot. |
subscribe(fn) |
Calls fn(state) on every state change; returns an unsubscribe function. |
on(event, fn) |
Listens to loadstart, load, error, select, clear, open or close details; returns an unsubscribe function. |
destroy() |
Cancels work, removes listeners and elements, restores attributes. |
State
getState() and subscribe() describe what the controller shows, for framework bindings and custom UI around it:
| Field | Description |
|---|---|
query |
The query of the last search (after beforeSearch), or '' for recent items. |
status |
idle, loading, results, empty, error or recent. |
open |
Whether the popup is visible. |
suggestions |
Rendered suggestions in keyboard order. |
sections |
{ id, label?, suggestions }[] as rendered. |
activeIndex |
The highlighted option, or -1. |
selected |
The selected suggestion, or null. |
Snapshots are immutable: a new object is published only when a field changes.
Plugins
A plugin is { name, setup(controller) }. setup runs once the controller exists and may return { beforeSearch?, transformSuggestions?, beforeSelect?, destroy? }. Hooks from the options run first, then each plugin in order; destroy runs with controller.destroy().
Helpers
All helpers are exported from @samline/autocomplete; the DOM-free ones also from @samline/autocomplete/core.
createSearch(options): the DOM-free pipeline behind the controller. Takes the source, sections, cache, filter, normalize, getLabel, maxResults and transformSuggestions options and returns{ run(query, { signal, input }), clearCache(), sections, local }.runreturns the result synchronously for local arrays and cache hits and a promise otherwise; results carrysections,count,cached,errors,failedandaborted.optionsFromDataset(input): reads options from the input’sdata-autocomplete*attributes.fromEndpoint({ endpoint, queryParam?, requestInit?, parseResponse?, mapResponse? }): returns the(query, { signal, input })source function used forendpoint. Reuse or wrap it in your ownsource.filterSuggestions(items, query, { getText, normalize? }): keeps the items whose text contains every word of the query. The default filter for array sources.normalizeText(text): lowercases and removes diacritics.highlight(text, query, normalize?): returns{ text, match }[]parts that keep the original characters.renderHighlight(element, parts): appends parts as text nodes and<mark data-autocomplete-highlight>elements (from@samline/autocomplete/vanilla).createCache({ max?, ttl? }): the LRU cache withget,set,clearandsize.createRecentStore({ key?, max?, getKey?, storage? }): a most-recent-first list withget,add,removeandclear, stored as JSON inlocalStorage(or thestorageyou pass) and in memory as a fallback.mapCommonResponse(payload): reads a root array orsuggestions,itemsordataarrays.parseJsonResponse(response): the default JSON parser.DEFAULT_MESSAGES: the English messages.
Browser registry
The CDN bundle (@samline/autocomplete/browser/global) defines window.Autocomplete. The same object is importable as Autocomplete (alias browser) from @samline/autocomplete or @samline/autocomplete/browser.
| Member | Description |
|---|---|
newAutocomplete({ id, options }) |
Enhances the input with that id and registers it; returns null if missing. |
getAutocomplete(id) |
The registered controller, or null. |
getAutocompletes() |
A copy of the registered controllers by id. |
destroyAutocomplete(idOrInput) |
Destroys and unregisters one controller. |
destroyAutocompletes() |
Destroys and unregisters every controller. |
available |
The live registry object. |
mount, unmount, refresh, getMounted |
The declarative mount; see above. |
autocomplete(target, options) |
Creates a controller without registering it. |
Registering an id again destroys the previous controller. Calling destroy() on a registered controller also unregisters it.
Declarative mount
| Function | Description |
|---|---|
mount({ defaults }) |
Enhances every input[data-autocomplete] now and as inputs are added; destroys removed ones. |
refresh() |
Re-scans the document. |
unmount() |
Stops observing and destroys every mounted controller. |
getMounted() |
A Map of mounted inputs to controllers. |
The standalone script calls mount() on load. Mounted inputs with an id are added to the registry, so getAutocomplete(id) returns them. Invalid attributes log an error and leave the input untouched.
| Attribute | Option |
|---|---|
data-autocomplete="/url" |
endpoint (the bare attribute marks the input) |
data-autocomplete-source |
source: a JSON array, or the selector of a <script type="application/json"> |
data-autocomplete-min-length, -debounce, -max-results, -offset |
numbers |
data-autocomplete-query-param |
queryParam; empty for null |
data-autocomplete-placement |
placement |
data-autocomplete-popover, -highlight, -cache, -search-on-focus |
booleans; present or "true", or "false" |
data-autocomplete-hidden-input |
hiddenInput name |
data-autocomplete-recent, -recent-label |
recent |
data-autocomplete-label-key, -value-key, -id-key |
field names for getLabel, getValue (defaults to the label key), getId |
data-autocomplete-loading, -empty, -error |
messages |
Events
All events bubble from the input.
| Event | detail |
|---|---|
autocomplete:loadstart |
{ query } |
autocomplete:load |
{ query, suggestions, sections, cached } |
autocomplete:error |
{ query, error, section } |
autocomplete:select |
{ suggestion, label, value, section } |
autocomplete:clear |
{ query } |
autocomplete:open |
{ query } |
autocomplete:close |
{ query } |
autocomplete:loadstart fires only when a source is called; array sources and cache hits go straight to autocomplete:load. sections lists { id, label?, suggestions } in order; a single source reports one entry with the id default. section is the section id, recent for a recent selection, or null for a single source.
Types
AutocompleteOptions<T>, AutocompleteController<T>, AutocompleteTarget, AutocompleteSource<T>, AutocompleteSourceFunction<T>, AutocompleteSourceContext, AutocompleteEndpoint, AutocompleteEndpointOptions<T>, AutocompleteRequestInit, AutocompleteParser, AutocompleteResponseMapper<T>, AutocompleteCacheOptions, AutocompleteCache<T>, AutocompleteSection<T>, AutocompleteState<T>, AutocompleteStatus, AutocompleteEventMap<T>, AutocompleteHooks<T>, AutocompleteTransformContext, AutocompletePlugin<T>, AutocompletePluginHooks<T>, AutocompleteSearch<T>, AutocompleteSearchOptions<T>, AutocompleteSearchResult<T>, MountAutocompleteOptions, AutocompleteSectionResult<T>, AutocompleteRecentOptions<T>, AutocompleteRecentStore<T>, AutocompleteStorage, CreateRecentStoreOptions<T>, AutocompleteHiddenInputOptions<T>, AutocompletePlacement, AutocompleteStatusState, AutocompleteStatusContext, AutocompleteResultsContext<T>, AutocompleteMessages, AutocompleteMessage, AutocompleteMessageContext, AutocompleteHighlightPart, AutocompleteRenderContext, AutocompleteNormalizer, FilterSuggestionsOptions<T>, AutocompleteSelectDetail<T>, AutocompleteLoadDetail<T>, AutocompleteErrorDetail, AutocompleteApi, AutocompleteAvailable and NewAutocompleteInput<T>.