Query suggestions
What you're building: a dropdown that suggests popular searches ("running shoes") as well as, or instead of, actual results ("Nike Pegasus 41").
Picking a suggestion fills the search box and runs that search. It does not open a record.
┌ Suggestions ───────┐ ← reads your Query Suggestions index
│ running shoes │
│ running socks │
├ Products ──────────┤ ← reads your products index
│ Nike Pegasus 41 │
└────────────────────┘
Before you start
Query suggestions come from a separate Algolia index that you create in the Algolia dashboard, under Search → your index → Query Suggestions. We cannot create it for you, and neither can the app.
Two things to know before you build:
- It is not on every Algolia plan. Check your plan first.
- It starts empty. Algolia builds the index from real searches on your site and rebuilds it daily. On a new or quiet site there is nothing to suggest yet, so the section stays hidden until visitors have searched. That is working correctly, not a fault.
What you need
- Applies toA Div inside the autocomplete dropdown
The section.
- Applies toThe section
Makes it a suggestions list rather than a results list.
- Applies toThe section
Your Query Suggestions index.
A suggestions section always needs its own . It cannot inherit the index from the autocomplete wrapper, because that one holds your records and this one holds queries.
Build it
Inside the section, put an autocomplete-template as usual and bind one text
field to . That is the attribute Algolia stores the
suggestion text in.
<div wf-algolia-element="autocomplete" wf-algolia-index="products">
<div
wf-algolia-element="autocomplete-section"
wf-algolia-index="products_query_suggestions"
wf-algolia-suggestions="true"
>
<div wf-algolia-element="autocomplete-section-label">Suggestions</div>
<div wf-algolia-element="autocomplete-template">
<div wf-algolia-field="query"></div>
</div>
</div>
</div>
Showing suggestions above your results
Add a second section for your records, pointed at your normal index. Order the sections in the Designer the way you want them read: suggestions first is the usual choice, since they are the shortcut and the records are the destination.
The app's Multi-source experience builds this shape for you.
Choosing one
Clicking a suggestion, or highlighting it with the arrow keys and pressing Enter, puts that text in the search box and re-runs the search. Every other section refreshes, and so does any results grid using the same search box.
Suggestions never navigate, even if your template contains a link.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The section never appears | The index has no suggestions yet | Wait for real searches, or check the index in Algolia |
| The section never appears | Query Suggestions is not on your Algolia plan | Check your plan |
| Every suggestion is blank | The template binds a field other than query | Bind the text field to query |
| Suggestions show your products, not searches | The section points at your records index | Point it at the Query Suggestions index |
| Picking one opens a page | Script older than the release that added this | Update to @candid-leap/wf-algolia@1 |
| Picking one does nothing | The section is missing wf-algolia-suggestions="true" | Add it to the section |
Related
Converting a section safely
Enabling suggestions keeps your existing source and fields. Choose the separate Query Suggestions index yourself; custom names are supported. The builder may suggest a known sibling index, but cannot verify its type from its name.
Use a query template and suggested index explicitly converts the section.
Undo suggestions conversion restores the previous source and fields while
you remain on that step. Confirm that the selected index was configured through
Algolia Query Suggestions and that the visible text binds to query. Empty,
loading and failed index lookups are different states; none verifies readiness.