connectors connectHierarchicalMenu

Edit this page


HierarchicalMenu connector provides the logic to build a custom widget that will give the user the ability to explore facets in a tree-like structure.

This is commonly used for multi-level categorization of products on e-commerce websites. From a UX point of view, we suggest not displaying more than two levels deep.

There’s a complete example available on how to write a custom HierarchicalMenu: hierarchicalMenu.js


const search= instantsearch(/* parameters */);

const makeHierarchicalMenu= instantsearch.connectors.connectHierarchicalMenu(
function renderFn(
renderOpts: HierarchicalMenuRenderingOptions,
isFirstRendering: boolean) {
// render the custom HierarchicalMenu widget
} );

const customHierarchicalMenu = makeHierarchicalMenu(instanceOpts: CustomHierarchicalMenuWidgetOptions);

Connector options


  • createURL(item.value) => string

    Creates an url for the next state for a clicked item.

  • itemsArray<HierarchicalMenuItem>

    Values to be rendered.

  • refine(item.value) => undefined

    Sets the path of the hierarchical filter and triggers a new search.

  • widgetParamsObject

    All original CustomHierarchicalMenuWidgetOptions forwarded to the renderFn.


  • valuestring

    Value of the menu item.

  • labelstring

    Human-readable value of the menu item.

  • countnumber

    Number of matched results after refinement is applied.

  • booleanisRefined

    Indicates if the refinement is applied.

  • data[Object]
    Default value: undefined

    n+1 level of items, same structure HierarchicalMenuItem (default: undefined).


  • attributesArray<string>

    Attributes to use to generate the hierarchy of the menu.

  • separator[string]
    Default value: '>'

    Separator used in the attributes to separate level values.

  • rootPath[string]
    Default value: null

    Prefix path to use if the first level is not the root level.

  • showParentLevel[boolean]
    Default value: false

    Show the siblings of the selected parent levels of the current refined value. This does not impact the root level.

  • limit[number]
    Default value: 10

    Max number of value to display.

  • sortBy[Array<string>|function]
    Default value: ['name:asc']

    How to sort refinements. Possible values: count|isRefined|name:asc|name:desc.

    You can also use a sort function that behaves like the standard Javascript compareFunction.

  • transformItems[(Array<object>) => Array<object>]

    Function to transform the items passed to the templates.

Can't find what you are looking for? Open an issue, we'll get back to you.