- Docs
- Changelog
Changelog
Every @samline/autocomplete release, newest first, with breaking changes, behavior changes and upgrade steps called out explicitly.
All notable changes to @samline/autocomplete are documented in this file. The format follows Keep a Changelog and the project adheres to Semantic Versioning.
[3.0.0] - 2026-11-15
Family conventions: one bundle name, one stylesheet name and pnpm. The old file names still ship as aliases.
Breaking changes
- The classic script no longer has a
defaultexport, sowindow.Autocomplete.defaultis gone, and the extrawindow.AutocompleteBundleglobal is removed. Usewindow.Autocomplete. @samline/autocomplete/browserno longer has a default export. Useimport { Autocomplete } from '@samline/autocomplete/browser'.- The standalone script is now
dist/browser/autocomplete.global.js(the./browser/globalexport points to it) and the stylesheet isdist/style.css(export./style.css).dist/browser/global.global.jsanddist/styles.css(export./styles.css) are still built as identical aliases.
Changed
- The standalone script is minified.
- The package installs with pnpm and runs its scripts with Bun; CDN examples are pinned to 3.0.0.
Tests
- Coverage thresholds (95 % statements, functions and lines, 90 % branches), gzip budgets for every public entry and browser tests in Chromium, Firefox and WebKit.
2.2.0 - 2026-11-14
Observable state, hooks, plugins, a headless search pipeline and a no-JavaScript setup. No breaking changes.
Added
- Controller
getState(),subscribe(listener)andon(event, listener), each returning an unsubscribe function where it applies. The state holdsquery,status,open,suggestions,sections,activeIndexandselected. controller.setValue(item)to prefill the selection, input text and hidden input without events.autocomplete:openandautocomplete:closeevents.- Hooks
beforeSearch(rewrite or skip a query),transformSuggestions(beforemaxResults) andbeforeSelect(veto). plugins:{ name, setup(controller) }returning hooks and adestroycallback.createSearch(options): the DOM-free pipeline (sources, sections, filtering, cache, partial failures) for custom rendering, synchronous for local arrays and cache hits.DEFAULT_SECTION_ID.- Declarative
mount({ defaults }),refresh(),unmount()andgetMounted()forinput[data-autocomplete], configured throughdata-autocomplete-*attributes;optionsFromDataset(input). The standalone script mounts on load, and mounted inputs with an id join the registry. - A “Recipes” guide (React, Vue, Alpine, Livewire, command palette, plugins, headless) and a “No JavaScript” example.
Changed
- The search pipeline moved into
createSearch, which the controller now uses; behavior is unchanged.
2.1.0 - 2026-11-14
Sections, recent selections, form fields, smarter placement and custom popup content. No breaking changes.
Added
sections: labelled groups (role="group") searched in parallel, each with its ownsource,maxResults,filterandcache. A failing section is dropped and reported; the error state shows only when every pending section fails and nothing matched.recent: recent selections shown when the empty input gets focus or ArrowDown, stored inlocalStoragewith a memory fallback.createRecentStore()andcontroller.recent.hiddenInput: a named hidden field (or an existing one) that holds the selected id, empties when the text changes and dispatcheschange.controller.hiddenElement.placement(auto,bottom,top) withdata-placement;autoflips above when there is no room below.popoverandoffset: render the popup in the top layer with the Popover API, pinned to the input on scroll and resize.renderStatus,renderHeaderandrenderFooter.- Event details:
sectionsonautocomplete:load,sectiononautocomplete:selectandautocomplete:error. - Stylesheet rules for groups, header, footer, top placement and popovers.
- “Sections” and “Forms” examples.
Changed
- The popup flips above the input when there is no room below. Set
placement: 'bottom'to keep it below. - Validation messages mention
sectionsalongsidesourceandendpoint.
2.0.0 - 2026-11-14
Sources beyond HTTP, caching, highlighting, a stricter listbox and the registry shared by the other @samline packages.
Breaking
- The browser registry follows the shared
@samlineshape:newAutocomplete({ id, options }),getAutocomplete(id),getAutocompletes(),destroyAutocomplete(idOrInput)anddestroyAutocompletes()replacecreate(target, options)anddestroy(id).newAutocompletelogs and returnsnullinstead of throwing when the id or input is missing. @samline/autocomplete/browseris now the registry as an ESM/CommonJS module. The standalone script moved to@samline/autocomplete/browser/global(the file is stilldist/browser/global.global.js).- Options are
<div role="option">elements instead of<button>, so they are no longer Tab stops.renderOptionreceives anHTMLElementand a thirdcontextargument. - The listbox now sits inside
[data-autocomplete-popup], which carries the positioning styles. Loading, empty and error messages render in[data-autocomplete-status]outside the listbox, instead of inside it withrole="status"/role="alert"; a separate polite live region announces them. Update selectors that targeted[data-autocomplete-list]for positioning. - Labels are highlighted by default. Set
highlight: falsefor plain text. - Function and endpoint results are cached per query for five minutes by default. Set
cache: falsefor the previous behavior. createAutocompleteControlleris removed; usecreateAutocompleteorautocomplete.- The default label and value also read a
namefield.
Added
source: a local array filtered in the browser, or(query, { signal, input }) => items, as an alternative toendpoint. Array sources default tominLength: 1anddebounce: 0.filterandnormalizeoptions; matching ignores case and accents by default.cache(true,falseor{ max, ttl }) andcontroller.clearCache().autocomplete:loadreportscached.highlightoption and<mark data-autocomplete-highlight>rendering.renderOptioncontext{ query, index, label, highlight }.messages.resultsand message functions of{ query, count }for translations and plurals.- Controller
popupElement,statusElementandliveElement. The listbox is labelled by the input’s<label>. - Helpers
fromEndpoint,filterSuggestions,normalizeText,highlight,renderHighlight,createCacheandDEFAULT_MESSAGES. - Entrypoints
@samline/autocomplete/core,@samline/autocomplete/vanillaand thestyle.cssalias. - Stylesheet: highlight custom properties and a forced-colors outline for the active option.
- A “Local data” example.
1.0.0 - 2026-11-13
First public release.
Added
createAutocomplete(input, options)(aliasautocomplete) turns an existing text input into an accessible remote combobox: debounce, abortable requests, stale-response protection, listbox rendering, keyboard and pointer selection, events and cleanup.- Options:
endpoint,queryParam,requestInit,parseResponse,mapResponse,getId,getLabel,getValue,renderOption,minLength,debounce,maxResults,searchOnFocus,messages,onSelectandonError. - Events
autocomplete:loadstart,autocomplete:load,autocomplete:error,autocomplete:selectandautocomplete:clear. - Keyboard: ArrowUp, ArrowDown, Home, End, Enter, Escape and Tab. Searches wait for IME composition to finish.
- Browser global
window.Autocompletewithcreate,destroy,availableandautocomplete, and an optional stylesheet themed with--autocomplete-*custom properties. - Website with examples and documentation at https://samline.github.io/autocomplete/.
Fixed (since the unpublished 0.1.0)
- Escape, Tab, clicking outside, selecting a suggestion and
close()cancel the pending debounced search and abort the request in flight. Before, a late response reopened the list after it was dismissed. - The standalone script defines
window.Autocompletewith its documented members. Before, the global was wrapped as{ default }.