Skip to main content
The hierarchicalMenu widget creates a navigation menu based on a hierarchy of facet attributes. It’s commonly used for category navigation with nested levels.

​
Usage

const hierarchicalMenu = instantsearch.widgets.hierarchicalMenu({
  container: '#hierarchical-categories',
  attributes: [
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
  ],
});

search.addWidget(hierarchicalMenu);

​
Examples

​
Basic Hierarchical Menu

instantsearch.widgets.hierarchicalMenu({
  container: '#categories',
  attributes: [
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
  ],
});

​
With Custom Separator

instantsearch.widgets.hierarchicalMenu({
  container: '#categories',
  attributes: ['categories.lvl0', 'categories.lvl1'],
  separator: ' / ',
});

​
With Show More

instantsearch.widgets.hierarchicalMenu({
  container: '#categories',
  attributes: ['categories.lvl0', 'categories.lvl1', 'categories.lvl2'],
  limit: 5,
  showMore: true,
  showMoreLimit: 15,
});

​
Without Parent Level

instantsearch.widgets.hierarchicalMenu({
  container: '#categories',
  attributes: ['categories.lvl0', 'categories.lvl1'],
  showParentLevel: false,
});

​
Options

​
container
string | HTMLElement
required
CSS Selector or HTMLElement to insert the widget.
​
attributes
string[]
required
Array of attribute names representing each hierarchical level.Example: ['categories.lvl0', 'categories.lvl1', 'categories.lvl2']
​
separator
string
default:"' > '"
Separator used between levels in the attribute values.
​
rootPath
string
Prefix path to use if the first level is not the root level.Example: 'Cameras & Camcorders > Digital Cameras'
​
showParentLevel
boolean
default:"true"
Show siblings of the selected parent level. When false, only shows the selected path.
​
limit
number
default:"10"
Maximum number of values to display at each level.
​
showMore
boolean
default:"false"
Whether to display a “Show more” button.
​
showMoreLimit
number
default:"20"
Maximum number of values when “Show more” is clicked.
​
sortBy
string[] | function
default:"['name:asc']"
How to sort refinements. Available values:
  • 'count:asc' / 'count:desc'
  • 'name:asc' / 'name:desc'
  • 'isRefined'
​
transformItems
function
Function to transform the items before rendering.
(items: object[]) => object[]
​
templates
object
Templates to customize the widget rendering.
​
cssClasses
object
CSS classes to add to the widget elements.

​
HTML Output

<div class="ais-HierarchicalMenu">
  <ul class="ais-HierarchicalMenu-list">
    <li class="ais-HierarchicalMenu-item ais-HierarchicalMenu-item--selected">
      <a class="ais-HierarchicalMenu-link" href="#">
        <span class="ais-HierarchicalMenu-label">Cameras & Camcorders</span>
        <span class="ais-HierarchicalMenu-count">1,287</span>
      </a>
      <ul class="ais-HierarchicalMenu-list ais-HierarchicalMenu-list--child">
        <li class="ais-HierarchicalMenu-item ais-HierarchicalMenu-item--selected">
          <a class="ais-HierarchicalMenu-link" href="#">
            <span class="ais-HierarchicalMenu-label">Digital Cameras</span>
            <span class="ais-HierarchicalMenu-count">170</span>
          </a>
        </li>
      </ul>
    </li>
  </ul>
</div>

​
Data Format

Your records must be formatted hierarchically: 
{
  "objectID": "123",
  "name": "Canon EOS",
  "categories": {
    "lvl0": "Cameras & Camcorders",
    "lvl1": "Cameras & Camcorders > Digital Cameras",
    "lvl2": "Cameras & Camcorders > Digital Cameras > DSLR"
  }
}
Each level must include the full path from the root.

​
Requirements

All hierarchical attributes must be declared as attributes for faceting in your Algolia index settings.

Build docs developers (and LLMs) love

Get started for freeTalk to us