Loading...
searchstack.dev
Sign In

Put the box on your page

Your movies-and-actors group becomes the thing a visitor actually touches.

If your front-end is a web page, @searchstack/autocomplete saves you work: a tiny, framework-agnostic JavaScript component that turns any <input> into an as-you-type box wired to your list or group. It handles debouncing, keyboard navigation, mobile full-screen mode and cancelled requests. You style the rows.

Try it

This box is wired to the live movies-and-actors group. Try matrix, hemsworth, dark or dream:

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

An input for it to bind to:

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

Then import the component and call attachGroup with the input's id, an API key scoped to suggest (it ships in your page, so keep it read-only), 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, escapeHtml } 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

Each result shows its name by default. Pass a template — a function that gets a result and returns HTML — to render richer rows, branching on the list_name a group result carries: 

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="${escapeHtml(r.image_url)}" width="40">
        <div><strong>${escapeHtml(r.name)}</strong><br><small>Actor</small></div>
      </div>`
    }
    return `<div class="row">
      <img src="${escapeHtml(r.poster_url)}" width="40">
      <div><strong>${escapeHtml(r.name)}</strong> <small>(${escapeHtml(r.year)})</small></div>
    </div>`
  }
})

Not using JavaScript? Call the API directly

Underneath, the plug-in makes one HTTPS request per keystroke to the suggest endpoint. 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 the matching records under results — the same data the box draws its rows from. interpretation is null unless a query rule rewrote the text:

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

Wire that into a Python backend, a Swift app or a Go service. Full request and response details are in the suggest reference.

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

Top