Components: the search box

This is the moment everything you built pays off. You have a movies-and-actors group that's searchable, filterable, and self-improving. Now let's put it in front of a visitor as a real search box — the part they actually touch.

That said, if your front-end is a web page, @searchstack/autocomplete saves you a lot of work. It's a tiny, framework-agnostic JavaScript component that turns any <input> into an as-you-type search box wired to your list or group. It handles debouncing, keyboard navigation, mobile full-screen mode and cancelled requests for you — you just style the rows.

Try it

Here's a box wired to a live movies-and-actors group on the public API. Type a film, an actor, or a word from a plot — try matrix, hemsworth, dark or dream:

This box is live: every keystroke calls the suggest endpoint on the Demo account’s movies-and-actors group with a read-only demo key, drawing films and actors with different row templates.

Add it to a page

First, an input for it to bind to:

<input id="movie-search" style="width:100%" />

Then import the component and call attachGroup. Pass the id of your input, an API key scoped to suggest (it ships in your page, so keep it read-only), then the account, the group name, and the group's current membership version:

<script type="module">
  import { attachGroup } from 'https://cdn.jsdelivr.net/npm/@searchstack/autocomplete@2/dist/searchstack-autocomplete.js'

  await attachGroup('movie-search', 'YOUR_SUGGEST_KEY', 'Demo', 'movies-and-actors', 3)
</script>

Prefer a build step? It's on npm:

npm install @searchstack/autocomplete

import { attachGroup } from '@searchstack/autocomplete'

await attachGroup('movie-search', 'YOUR_SUGGEST_KEY', 'Demo', 'movies-and-actors', 3)

For a single list, call attachList instead — same arguments, but pass the list name and its version number.

Style each result

Out of the box each result shows its name. To render richer rows, pass a template — a function that gets a result and returns HTML. Because you're searching a group, each result carries a list_name, so you can render a film and a person differently from the one box:

await attachGroup('movie-search', 'YOUR_SUGGEST_KEY', 'Demo', 'movies-and-actors', 3, {
  template: (r) => {
    if (r.list_name === 'actors') {
      return `<div class="row">
        <img src="${r.image_url}" width="40">
        <div><strong>${r.name}</strong><br><small>Actor</small></div>
      </div>`
    }
    return `<div class="row">
      <img src="${r.poster_url}" width="40">
      <div><strong>${r.name}</strong> <small>(${r.year})</small></div>
    </div>`
  }
})

Not using JavaScript? Call the API directly

The plug-in is a convenience, not a requirement. Underneath, it makes one HTTPS request per keystroke to the suggest endpoint — the exact thing you built. You can make that same request from any language and render the results however you like. It's a POST to suggest/group/{account}/{group}/{version}/{query} (drop the /group segment for a single list), with your suggest key in the X-API-Key header:

curl -X POST "https://api.searchstack.dev/suggest/group/Demo/movies-and-actors/3/hemsworth" \
  -H "X-API-Key: YOUR_SUGGEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "size": 6 }'

You get back a plain list of matching records — the same data the box draws its rows from:

[
  { "list_name": "actors", "name": "Liam Hemsworth", "image_url": "…" },
  { "list_name": "actors", "name": "Chris Hemsworth", "image_url": "…" }
]

Wire that into a Python backend, a Swift app, a Go service — wherever your search box lives. The plug-in just spares you the front-end plumbing when it happens to be a web page. Full request and response details are in the suggest reference.

That's the whole tutorial. You started with an empty account and finished with a live, self-improving search over two lists — reachable from any language, with no search server to run and no index to manage.