Search or browse
These look similar and behave differently. Choosing wrong is the most common reason a page "almost" works.
The distinction
Search starts empty and reacts to typing. Someone has a word in mind.
Browse starts full and reacts to filtering. Someone wants to see what is there and narrow it down.
| Search | Browse | |
|---|---|---|
| Starts when | The user types | The page loads |
| Before any input | Nothing shown | First page of results |
| Root element | wf-algolia-element="search-input" | wf-algolia-element="browse" wrapper |
| Filters | Rarely | Yes, inside the wrapper |
| Pagination | No | Yes |
| Shareable URL | No | Optional |
| Sorting | No | Yes, via replica indices |
The structural difference that matters
Search is driven by an input. The input is the root; results render wherever you point them.
Browse is driven by a wrapper. The wrapper is a container, and the filters, results, pagination and sort controls all live inside it. That containment is not stylistic — it is how the script knows which controls belong to which result set, and it is what lets one page carry two independent browse regions.
A filter placed outside its browse wrapper will render its options and then never affect anything. It is the single most common structural mistake, and it produces no error at all.
Most sites need both
A shop has a header search box and a catalogue page. They are separate features that happen to query the same index — build them separately.
A browse page can have a search box
Confusingly, browse supports its own text input: browse-search. It refines the
result set already on screen, rather than starting one.
Use browse-search when the box lives inside a browse wrapper and narrows what
is displayed. Use search-input when the box is the feature. The public API's
getQuery() prefers browse-search when both are present, which tells you which
one the script considers primary on such a page.
Which am I building?
Ask what the page looks like with nothing typed:
- Empty, waiting → search
- Already showing results → browse