- Docs
- Install and search
Install and search
Install @samline/autocomplete with a package manager or a script tag, add the input and create your first search from an endpoint, a function or a local array.
Package / ESM
npm install @samline/autocomplete
<div class="field" style="position: relative">
<label for="city">City</label>
<input id="city" type="text" />
</div>
import { createAutocomplete } from '@samline/autocomplete'
import '@samline/autocomplete/style.css'
const controller = createAutocomplete('#city', {
endpoint: '/api/cities',
getId: city => city.id,
getLabel: city => city.name,
onSelect: city => console.log('Selected', city),
})
The request is GET /api/cities?q=<query>. Return an array, or an object with suggestions, items or data; otherwise use mapResponse. Results are cached per query for five minutes. The wrapper around the input needs position: relative, because the default popup is absolutely positioned under it.
No endpoint? Pass a source instead: an array filtered in the browser, or any function that returns suggestions.
createAutocomplete('#state', { source: ['Jalisco', 'Michoacán', 'Querétaro'] })
createAutocomplete('#user', {
source: (query, { signal }) => api.users.search(query, { signal }),
getLabel: user => user.name,
})
HTML / CDN
For Shopify, WordPress or plain HTML pages without a build step, load the stylesheet and the browser bundle. Pin the version in production.
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@samline/autocomplete@3.0.0/dist/style.css"
/>
<script src="https://cdn.jsdelivr.net/npm/@samline/autocomplete@3.0.0/dist/browser/autocomplete.global.js"></script>
<script>
window.Autocomplete.newAutocomplete({ id: 'city', options: { endpoint: '/api/cities' } })
</script>
Autocomplete.newAutocomplete({ id, options }) enhances the input with that id and registers the controller; Autocomplete.getAutocomplete(id) reads it back and Autocomplete.destroyAutocomplete(id) removes it. Autocomplete.autocomplete(input, options) creates one without the registry. The registry has the same shape as the other @samline packages.
Frameworks and CMS
There is no adapter: create the controller once the input exists in the DOM and destroy it when the input leaves. In React:
import { useEffect, useRef } from 'react'
import { createAutocomplete } from '@samline/autocomplete'
export function CitySearch() {
const input = useRef(null)
useEffect(() => {
const controller = createAutocomplete(input.current, { endpoint: '/api/cities' })
return () => controller.destroy()
}, [])
return (
<div style={{ position: 'relative' }}>
<label htmlFor="city">City</label>
<input id="city" ref={input} type="text" />
</div>
)
}
Vue (onMounted / onBeforeUnmount) and Svelte (onMount returning the cleanup) follow the same pattern. In Shopify themes or WordPress, use the HTML / CDN files and call window.Autocomplete.newAutocomplete after the input is in the page.
Requirements
- Modern browsers with
fetch,AbortControllerand Unicode property escapes in regular expressions. Node 20 or newer for server-side imports. - No runtime dependencies. The stylesheet is optional.
Working starter files
A complete page that runs as-is. It searches the public list of cities used by these docs.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Autocomplete starter</title>
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@samline/autocomplete@3.0.0/dist/style.css"
/>
</head>
<body>
<div style="position: relative; max-width: 28rem">
<label for="city">City</label>
<input id="city" type="text" />
</div>
<script src="https://cdn.jsdelivr.net/npm/@samline/autocomplete@3.0.0/dist/browser/autocomplete.global.js"></script>
<script>
window.Autocomplete.newAutocomplete({
id: 'city',
options: {
endpoint: 'https://samline.github.io/autocomplete/cities.json',
mapResponse: (payload, response, query) =>
payload.results.filter(city => city.name.toLowerCase().includes(query.toLowerCase())),
getId: city => city.key,
getLabel: city => city.name,
},
})
</script>
</body>
</html>