Why does the hierarchical menu widget only retrieve the first level in the API facets parameter?

A hierarchical menu is designed to work with a hierarchy of facet attributes such as lvl0, lvl1, and lvl2, while the search API returns facet values for the attributes explicitly requested in the facets parameter.

For both the hierarchicalMenu and connectHierarchicalMenu widgets, it’s expected to see only the top-level attribute in the initial facets parameter.

This is because, for these widgets, InstantSearch treats the first attribute in the attributes array as the widget’s "identifier" and so only the root level is fetched initially.

Deeper levels are then retrieved after a refinement is applied i.e. once a user selects a lvl0 value, InstantSearch will then request and display the corresponding lvl1 values.

For example, with this configuration:

hierarchicalMenu({
  container: '#hierarchical-menu',
  attributes: [
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
  ],
});

you may see an initial request like:

{
  "requests": [
    {
      "indexName": "products",
      "facets": ["brand", "color", "hierarchicalCategories.lvl0", "rating"],
      "hitsPerPage": 20,
      "page": 0
    }
  ]
}

In this case, hierarchicalCategories.lvl1 and hierarchicalCategories.lvl2 aren’t missing or misconfigured. They’re retrieved after a user refines the hierarchy by selecting a lvl0 value.

If you need all levels to be available independently (rather than progressively), you would need to use separate refinementList widgets instead of a hierarchical menu widget.