# @searchstack/autocomplete
[](https://www.npmjs.com/package/@searchstack/autocomplete)
**Drop-in autocomplete and typeahead search UI for any text input.** Anchored dropdown on
desktop, full-screen modal on mobile, search history built in β and no framework required.
Works with React, Vue, Svelte, or plain HTML, because it attaches to an element you already have.
π **[Try it live](https://searchstack.dev/demos)** β no signup.
Suggestions are served by the [Search Stack](https://searchstack.dev) search API, fetched via
[`@searchstack/public-api`](https://www.npmjs.com/package/@searchstack/public-api). You'll need a
free API key ([10,000 records, every feature, no card](https://searchstack.dev)).
## Install
```
npm install @searchstack/autocomplete
```
## 30-second start
```html
```
```js
import { attachList } from '@searchstack/autocomplete';
await attachList('search', 'sk_...', 'my-account', 'my-list', 1);
```
That's a working typeahead. Everything below is optional customisation.
## Usage
```js
import { attachList, attachGroup } from '@searchstack/autocomplete';
// Suggest over a single List:
await attachList('my-textbox-id', 'sk_...', 'my-account', 'my-list', 1, {
template: (data) => `
${data.name}
`,
selected: (data) => console.log('selected', data),
search: (query) => console.log('search', query),
});
// ...or across every List in a Group (pass the group's membership version):
await attachGroup('my-textbox-id', 'sk_...', 'my-account', 'my-group', 3, {
template: (data) => `
${data.name}
`,
});
```
Both resolve with the list element once attached. If the textbox is not yet in the DOM they wait for up to 30 seconds before rejecting.
- `attachList(textboxId, apiKey, accountName, listName, version, options)` β suggest over a single List.
- `attachGroup(textboxId, apiKey, accountName, groupName, version, options)` β suggest across a Group of Lists, using the group's membership version.
- `attachAsk(textboxId, apiKey, accountName, listName, version, options)` β everything `attachList` does, plus a grounded answer panel. See below.
The first two are identical apart from which endpoint they hit; `apiKey` is the second argument and is required (it authenticates the request and overrides any `api_key` in `options`).
## Ask
> **Requires 2.4.0 or later.** `attachAsk` and `attachAskLauncher` were added in 2.4.0. Importing
> them from an older build fails the **whole module**, not just the Ask call β a missing named export
> is an ES-module *link* error, so `attachList` never runs either and the search box goes down with
> it. Loading from a CDN? Pin the exact version (`@2.4.0`), not the `@2` range: jsDelivr can keep
> serving a cached older build behind a range for hours after a release.
`attachAsk` is `attachList` plus an answer. Typing behaves exactly as before β same suggestions, same
speed β and an **"Ask this" row** appears beneath the suggestions, opening an overlay that streams an
answer and links back to every section it used.
Four ways to reach it, so it never becomes a mouse-only feature:
| | |
| --- | --- |
| **Click** the row | |
| **β past the last suggestion** | The row is the last stop in the same list the arrow keys walk |
| **Type a `?`** | Ends the query in a question mark and the row is pre-selected, so **Enter** answers straight away |
| **Cmd-K / Ctrl-K** | From anywhere on the page |
Inside the overlay, a trailing `?` **starts the answer on its own** β no Enter needed. It waits
`ask_auto_delay` (700ms) after the last keystroke so a sentence is only answered once it is finished,
and it will not answer the same wording twice; both guards exist because every answer is a paid call.
**β** and **β** walk the cited and related sections, and **Esc** closes.
**Enter is unchanged unless the Ask row is selected.** With no `?` and no arrowing, Enter still fires
`searchstack-search` exactly as it always did, so an existing jump-to-top-match handler keeps working.
Arrowing into the suggestions clears the question-mark selection β an explicit move beats an inferred
default.
```js
import { attachAsk } from '@searchstack/autocomplete';
await attachAsk('search', 'sk_...', 'my-account', 'my-list', 1, {
ask_endpoint: '/api/ask', // your backend β see below
template: (data) => `
${data.name}
`,
});
```
**Suggestions go straight from the browser to the search API on the key above. The answer does not.**
Generating an answer needs a model key, and a model key must never ship in a page β so `ask_endpoint`
points at your own backend, which retrieves, calls the model, and streams the result back.
Your endpoint receives `POST { "question": "β¦" }` and replies with server-sent events:
| Event | Payload | When |
| --- | --- | --- |
| `sources` | `{ sources: [{ marker, title, page, url, content }] }` | First, before generation β so the panel paints results immediately instead of sitting blank |
| `delta` | `{ text }` | Each chunk of the answer |
| `done` | `{ answered, reason, citations, cached }` | Last |
| `error` | `{ message }` | Instead of `done` |
Cite sections in the answer text as `[^1]`, matching a source's `marker`. The widget renders each one
as a link to that source's `url`.
**Strip any marker your retrieval did not produce before you send it.** The widget will not render a
marker it cannot resolve, but that is a last line of defence, not the guarantee β the guarantee has to
be that an uncited claim never leaves your server. A cited answer is the only reason a reader should
trust one, so a citation that goes nowhere is worse than no answer.
An answer that cannot be grounded should come back with `answered: false`, a plain sentence, and the
sources still populated: the sections are usually what the reader wanted anyway, and a refusal over an
empty panel reads as a broken feature.
Ask options β all optional, all on the same options object:
| Option | Default | Description |
| --- | --- | --- |
| `ask_endpoint` | `/api/docs/ask` | Your SSE endpoint |
| `ask_row_label` | `Ask this` | Label on the pinned row |
| `ask_placeholder` | `Ask a questionβ¦` | Placeholder in the overlay |
| `ask_thinking_label` | `Looking through the documentationβ¦` | Shown while streaming |
| `ask_sources_label` | `Answered from` | Heading above cited sources |
| `ask_results_label` | `Related sections` | Heading above the rest |
| `ask_error_label` | `Something went wrong producing that answer.` | Shown on failure |
| `ask_hotkey` | `true` | Bind Cmd-K / Ctrl-K |
| `ask_on_question_mark` | `true` | Treat a trailing `?` as intent to ask β pre-selects the row, and auto-starts in the overlay |
| `ask_auto_delay` | `700` | Pause after the last keystroke before an auto-started answer fires, in ms |
| `ask_feedback` | `true` | Show the thumbs row |
| `ask_link` | β | `(url) => url`, to rewrite links before navigation |
| `ask_rated` | β | `(rating, question) => void`, for your own telemetry |
### Ask without a search box
For a page that has no search box to hang Ask off β a home page, a footer, a help menu β use
`attachAskLauncher`. It wires any element to open the same overlay, fetches no suggestions, and needs
no search key:
```html
```
```js
import { attachAskLauncher } from '@searchstack/autocomplete';
await attachAskLauncher('ask', { ask_endpoint: '/api/ask' });
```
The element decides the shape:
| Element | Opens on | Use it when |
| --- | --- | --- |
| `