Skip to main content

Cascading filters

What you're building: filters that depend on each other — picking a country narrows the region list, picking a region narrows the city list.

The classic case is location, but the pattern fits any nested data: make then model, department then team.

What you need​

  • Applies toThe parent filter group

    Names this group so children can point at it.

  • Applies toThe child filter group

    Says which parent this group depends on.

Build it​

Give the parent an id, and point each child at it:

<div
  wf-algolia-element="filter-group"
  wf-algolia-field="country"
  wf-algolia-group-id="country"
></div>

<div
  wf-algolia-element="filter-group"
  wf-algolia-field="region"
  wf-algolia-refines="country"
  wf-algolia-group-id="region"
></div>

<div wf-algolia-element="filter-group" wf-algolia-field="city" wf-algolia-refines="region"></div>

A group can be both a child and a parent, which is how you get three levels or more.

Before the parent is chosen​

decides what a child does while its parent has no selection:

  • disable (the default) — visible but not interactive
  • hide — not rendered at all

disable communicates that more filters exist. hide keeps a long panel short.

Hierarchical facets are a different thing​

If your data is a single hierarchy stored in one field — Clothing > Shoes > Trainers — you want hierarchical filters, not cascading groups.

Cascading groups are separate facets that happen to relate. Hierarchical is one facet with levels.

Cycles are detected, not tolerated

Pointing two groups at each other logs Cycle detected in hierarchy at and stops resolving. Each wf-algolia-refines must point up the chain, never sideways or back.

Troubleshooting​

SymptomCauseFix
The child never enablesThe parent's wf-algolia-group-id does not match the child's wf-algolia-refinesThey are exact strings
The child shows every valueIt is not actually scoped — check for a typo in refinesBoth attributes must be present
Cycle detected in hierarchy atTwo groups reference each otherMake the chain one-directional
refreshChildGroup failed:The child could not reload after a parent changeCheck the child's field exists as a facet