Browse
What you're building: a listing page that shows results as soon as it loads, and narrows as people filter, sort and paginate.
Browse is built around a wrapper. Everything that belongs to the listing — filters, results, pagination, sort — lives inside it. That containment is what lets the script know which controls drive which result set.
What you need
- Applies toA Section or Div wrapping the whole listing
The wrapper. Everything else goes inside it.
- Applies toThe browse wrapper
Which index this listing queries.
- Applies toA Div inside the wrapper
Where results are rendered.
- Applies toOne card inside the results Div
Cloned once per result.
Build it
1. Wrap the listing. Put and on the Section that contains the whole feature.
2. Add results and a template, exactly as in Search.
3. Publish. The page now loads with the first page of results.
Everything below is optional and can be added one piece at a time.
A filter group placed outside the browse wrapper renders its options and then never affects anything, with no error. It is the most common structural mistake on a browse page. If a filter looks right but does nothing, check its position in the Navigator first.
Page size and pagination
sets how many results load at a time.
chooses the style — see Pagination for the values and the controls each one needs.
shifts the scroll position when a new page loads, so a sticky header does not cover the first row.
Shareable URLs
Add to the wrapper and the current filters, sort and page are written to the URL. Copying that URL reproduces the same view, and the browser back button steps through it.
Leave it off for a listing embedded in a larger page, where changing the URL would be surprising.
Always-on filters
Sometimes a listing should be permanently restricted — a category page that only ever shows one category, regardless of what the visitor picks.
applies a filter that visitors cannot remove. It is combined with, rather than replaced by, whatever they select.
Write it as a field and a value, on two attributes:
<section
wf-algolia-element="browse"
wf-algolia-index="products"
wf-algolia-base-filter-field="category"
wf-algolia-base-filter-value="Shoes"
></section>
The value stands alone, which makes it easy to bind to a CMS field so one template page serves every category.
field:value form is deprecatedstill parses, and warns once. It takes one field and one value and supports nothing below this line. See Deprecations.
Several values in one field
is comma-separated.
decides how those values
combine: or (the default) matches any of them, and requires all of them.
<section
wf-algolia-element="browse"
wf-algolia-index="products"
wf-algolia-base-filter-field="category"
wf-algolia-base-filter-value="shoes,boots"
wf-algolia-base-filter-match="or"
></section>
and is only meaningful on a field that holds several values per record, such
as a tags array.
Several fields
Add a numbered clause for each extra field: -field-2 and -value-2, then
-3, and so on. Each clause takes its own -match suffix
(wf-algolia-base-filter-match-2).
<section
wf-algolia-element="browse"
wf-algolia-index="products"
wf-algolia-base-filter-field="category"
wf-algolia-base-filter-value="shoes,boots"
wf-algolia-base-filter-field-2="brand"
wf-algolia-base-filter-value-2="Nike"
></section>
combines the clauses with each
other: and (the default) requires every clause, or accepts any of them. Note
that logic="or" flattens everything into a single "any of these" group, so a
clause-level match="and" cannot survive alongside it.
A clause with a value but no field is ignored, with a console warning naming the
clause number. An unrecognised -match or -logic value warns and falls back to
its default.
The same parser backs the whole family. A facet stat reads the same base-filter attributes off itself or its nearest scoped ancestor; a static list reads the same shape spelled .
It does not appear as a filter chip and cannot be cleared. If people should be able to remove it, it is an ordinary filter with a preselected value, not a base filter.
A search box inside browse
Use for a text input
that narrows the listing already on screen. That is different from
search-input, which starts a search — see
Search or browse.
Counts and empty states
- renders the number
of matches.
wf-algolia-text-templatecontrols the wording. - is shown only when nothing matches.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Page loads empty | No wf-algolia-index on the wrapper | Add it — browse cannot infer the index |
| Filters do nothing | They sit outside the browse wrapper | Move them inside |
| Results ignore the category | A base filter is set that you forgot about | Check the wrapper for wf-algolia-base-filter |
| Pagination controls do nothing | wf-algolia-pagination not set, or the controls are outside the wrapper | See Pagination |
| Back button does not restore filters | URL sync is off | Add wf-algolia-url-sync="true" |