Filters
What you're building: controls that narrow a browse listing — a category checkbox list, a price range, a brand dropdown.
Every filter is a filter group: one element that names the facet it filters, containing a template for one option. The script fills in the values from Algolia.
What you need
- Applies toA Div inside the browse wrapper
The group. One per facet.
- Applies toThe filter group
Which Algolia facet this filters on.
- Applies toThe filter group
Which index the facet lives in.
- Applies toOne option inside the group
Cloned once per facet value.
A Webflow reference field syncs as internal item IDs, so a filter group pointed
straight at it renders IDs instead of names. Map the property you want first:
in the app's field mapping, a reference row offers Add field from
Collection, which produces a real attribute such as actor_name. Declare
that as a facet in Algolia and point wf-algolia-field at it.
Multi-reference fields become arrays, which is exactly the shape a facet wants, so no other change is needed. See Reference and multi-reference fields.
Build it
1. Add the group inside your browse wrapper, with the facet name in .
2. Design one option — a checkbox, its label, and optionally a count — and mark it .
3. Mark the parts inside the template:
- — the value's name
- — how many results carry it
4. Publish.
A filter group pointed at a field that is not in Configuration → Facets will render nothing and narrow nothing. This is configuration on Algolia's side, not something an attribute can fix — see Algolia setup.
Choosing a variant
The same group markup produces different controls depending on what you put in the template and which options you set.
| Variant | Use it for |
|---|---|
| Checkbox | Several values at once |
| Radio | Exactly one value |
| Range | Numeric minimum and maximum |
| Select | Long lists, in a dropdown |
| Hierarchical | Nested categories |
| Comparison | Greater than, less than |
| Dynamic | Facets discovered at runtime |
| Toggle | One on/off switch |
How multiple selections combine
decides what happens when someone ticks two boxes in the same group:
or(the default) — results matching either valueand— only results matching both
or is right for most category filters. and suits tags, where narrowing is the
point.
Preselecting a value
selects a value when the page loads. Unlike a base filter, the visitor can clear it.
Long value lists
- caps how many values are shown.
- and label the toggle that reveals the rest.
- Hidden values get the class from
data-hideclass—is-hiddenby default — so you style the collapsed state in Webflow.
For very long lists, add a search box over the values: see Filter search.
Ordering the values
reorders the options:
| Value | Order |
|---|---|
natural | As Algolia returns them — by result count |
alpha | A→Z by the stored value |
count | Most results first |
selected-first | Selected values pinned to the top |
selected-alpha-zero-last | Selected first, then A→Z, with zero-count values last |
selected-first is worth knowing about for long lists: without it, ticking a
value near the bottom can push it out of view on the next render.
Keeping a selection visible
keeps a selected value on screen even when the newest results no longer contain it. Without it, a selection can vanish from the list while still being applied, which reads as a bug.
Showing what is selected
- renders a removable chip per active selection — see the Filter Tags component.
- renders how many values are active in one group.
Applying on a button instead of instantly
Set and selections accumulate until a button commits them. See Deferred apply.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| The group renders no options | The facet is not declared in Algolia, or the field name is wrong | Check Configuration → Facets |
| Options render but nothing narrows | The group sits outside the browse wrapper | Move it inside |
| Ticking two boxes returns nothing | wf-algolia-match="and" with values that never co-occur | Use or |
| Counts are always zero | The facet is declared but not returned for this query | Check the index and any base filter |
| A value search box does nothing | The facet is filter-only, not searchable | See Filter search |
| Options are long random-looking IDs | The field is a Webflow reference, indexed as item IDs | Map the referenced property, see the tip above |
| A renamed referenced item still shows its old name | The parent item did not change, so the sync skipped it | Sync the collection (manual mode) or Force reindex (webhook mode) |