Put the box on your page

This is the step where you rebuild what you saw at the start. Your movies-and-actors group is searchable and filterable; now it becomes the thing a visitor actually touches.

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 the live movies-and-actors group — the same one the finished example at the top of this lesson uses. 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 — the field you met in the last step — 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.

Go deeper: Every option, event and CSS variable in the reference.