- Docs
- Recipes for your stack
Recipes for your stack
Plain HTML with data attributes, React, Vue and Alpine wrappers, Livewire forms, a command palette, plugins and a fully headless search.
Every recipe uses the public API only; there is no adapter package to install.
Plain HTML, no JavaScript
The standalone script mounts every input[data-autocomplete] on load and as inputs are added or removed.
<script type="application/json" id="states">
["Jalisco", "Michoacán", "Nuevo León", "Querétaro", "Yucatán"]
</script>
<label for="state">State</label>
<input id="state" data-autocomplete data-autocomplete-source="#states" />
<label for="city">City</label>
<input
id="city"
data-autocomplete="/api/cities"
data-autocomplete-label-key="name"
data-autocomplete-id-key="id"
data-autocomplete-hidden-input="city_id"
data-autocomplete-recent
/>
<script src="https://cdn.jsdelivr.net/npm/@samline/autocomplete@3.0.0/dist/browser/autocomplete.global.js"></script>
Mounted inputs with an id are available through Autocomplete.getAutocomplete(id). With a bundler, call mount({ defaults }) yourself; defaults carries options that attributes cannot express, such as renderOption.
React
subscribe and getState plug straight into useSyncExternalStore.
import { useEffect, useRef, useState, useSyncExternalStore } from 'react'
import { createAutocomplete } from '@samline/autocomplete'
const idle = { status: 'idle', open: false, suggestions: [], selected: null }
export const useAutocomplete = options => {
const ref = useRef(null)
const [controller, setController] = useState(null)
useEffect(() => {
const instance = createAutocomplete(ref.current, options)
setController(instance)
return () => instance.destroy()
}, [])
const state = useSyncExternalStore(
listener => controller?.subscribe(listener) ?? (() => {}),
() => controller?.getState() ?? idle
)
return { ref, controller, state }
}
export const CitySearch = () => {
const { ref, state } = useAutocomplete({ endpoint: '/api/cities', getLabel: city => city.name })
return (
<div style={{ position: 'relative' }}>
<label htmlFor="city">City</label>
<input id="city" ref={ref} />
<p>{state.selected ? `Selected ${state.selected.name}` : 'Nothing selected'}</p>
</div>
)
}
Vue
import { onBeforeUnmount, onMounted, ref, shallowRef } from 'vue'
import { createAutocomplete } from '@samline/autocomplete'
export const useAutocomplete = options => {
const input = ref(null)
const state = shallowRef(null)
let controller
onMounted(() => {
controller = createAutocomplete(input.value, options)
state.value = controller.getState()
controller.subscribe(next => (state.value = next))
})
onBeforeUnmount(() => controller?.destroy())
return { input, state }
}
Alpine
<div
x-data="{ city: null }"
x-init="
const controller = Autocomplete.autocomplete($refs.input, { endpoint: '/api/cities' })
controller.on('select', ({ suggestion }) => (city = suggestion))
controller.on('clear', () => (city = null))
"
style="position: relative"
>
<label for="city">City</label>
<input id="city" x-ref="input" />
<p x-text="city ? city.name : 'Nothing selected'"></p>
</div>
Server-rendered forms (Laravel, Rails, Django, Livewire)
hiddenInput submits the id with the form. setValue prefills an edit form without dispatching events.
const controller = createAutocomplete('#city', {
endpoint: '/cities/search',
getId: city => city.id,
getLabel: city => city.name,
hiddenInput: 'city_id',
})
// Editing an existing record:
controller.setValue({ id: 42, name: 'Guadalajara' })
The hidden input dispatches a bubbling change event when its value changes. With Livewire, push the selection explicitly so the component never depends on hidden-field events:
controller.on('select', ({ suggestion }) => $wire.set('cityId', suggestion.id))
controller.on('clear', () => $wire.set('cityId', null))
Command palette
Sections and recent selections make a ⌘K palette in a few lines. popover: true keeps it above dialogs and clipped containers.
const palette = createAutocomplete('#palette', {
sections: [
{ id: 'actions', label: 'Actions', source: [{ id: 'new', label: 'New document' }] },
{ id: 'pages', label: 'Pages', source: (query, { signal }) => searchPages(query, { signal }) },
],
minLength: 1,
recent: { label: 'Recent' },
popover: true,
onSelect: item => run(item),
})
document.addEventListener('keydown', event => {
if (event.key === 'k' && (event.metaKey || event.ctrlKey)) {
event.preventDefault()
palette.element.focus()
}
})
Plugins
A plugin is a name and a setup(controller) function. It can listen with on() and subscribe(), and return hooks plus a destroy callback. Hooks from the options run first, then each plugin in order.
const analytics = track => ({
name: 'analytics',
setup: controller => {
const offLoad = controller.on('load', ({ query, suggestions }) =>
track('autocomplete_search', { query, results: suggestions.length })
)
const offSelect = controller.on('select', ({ value, section }) =>
track('autocomplete_select', { value, section })
)
return {
destroy: () => {
offLoad()
offSelect()
},
}
},
})
const dedupe = getKey => ({
name: 'dedupe',
setup: () => ({
transformSuggestions: items =>
items.filter(
(item, index) => items.findIndex(other => getKey(other) === getKey(item)) === index
),
}),
})
createAutocomplete('#city', {
endpoint: '/api/cities',
plugins: [analytics(window.track), dedupe(city => city.id)],
})
The hooks are also plain options: beforeSearch(query, input) returns a new query or false to skip, transformSuggestions(items, { query, section }) reorders before maxResults applies, and beforeSelect(item, input) returns false to keep the list open.
Headless
createSearch is the DOM-free pipeline behind every controller: sources, sections, local filtering, caching and partial failures. Render the results however you like.
import { createSearch } from '@samline/autocomplete'
const search = createSearch({
sections: [
{ id: 'cities', label: 'Cities', source: cities },
{ id: 'people', label: 'People', source: (query, { signal }) => api.people(query, { signal }) },
],
})
let controller
input.addEventListener('input', async () => {
controller?.abort()
controller = new AbortController()
const result = await search.run(input.value, { signal: controller.signal, input })
if (result.aborted) return
render(result.sections)
})
run() returns the result directly when every section is a local array or a cache hit, and a promise otherwise, so await covers both. You keep responsibility for ARIA and keyboard support when you render yourself.