hierarchicalMenu

Signature

hierarchicalMenu({
  container: string | HTMLElement,
  attributes: string[],
  // Optional parameters
  limit?: number,
  showMore?: boolean,
  showMoreLimit?: number,
  separator?: string,
  rootPath?: string,
  showParentLevel?: boolean,
  sortBy?: string[] | function,
  templates?: object,
  cssClasses?: object,
  transformItems?: function,
});

Import

import { hierarchicalMenu } from 'instantsearch.js/es/widgets';

View demo

The hierarchicalMenu widget displays a hierarchical navigation menu, based on facet attributes. To create a hierarchical menu:

Decide on an appropriate facet hierarchy
Determine your attributes for faceting from the dashboard or with an API client
Display the UI with the hierarchical menu widget.

To learn more, see Facet display.

Requirements

The objects to use in the hierarchical menu must follow this structure:

JSON

[
  {
    "objectID": "321432",
    "name": "lemon",
    "categories": {
      "lvl0": "products",
      "lvl1": "products > fruits"
  },
  {
    "objectID": "8976987",
    "name": "orange",
    "categories": {
      "lvl0": "products",
      "lvl1": "products > fruits"
    }
  }
]

You can also provide more than one path for each level:

JSON

[
  {
    "objectID": "321432",
    "name": "lemon",
    "categories": {
      "lvl0": ["products", "goods"],
      "lvl1": ["products > fruits", "goods > to eat"]
    }
  }
]

By default, the separator is > (with spaces), but you can use a different one by using the separator option.

By default, the count of the refined root level is updated to match the count of the actively refined parent level. Keep the root level count intact by setting persistHierarchicalRootCount in instantsearch.

Examples

JavaScript

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

Options

container

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

hierarchicalMenu({
  // ...
  container: '#hierarchical-menu',
});

attributes

string[]

required

The name of the attributes to generate the menu with.To avoid unexpected behavior, you can’t use the same attribute prop in a different type of widget.

JavaScript

hierarchicalMenu({
  // ...
  attributes: [
    "categories.lvl0",
    "categories.lvl1",
    "categories.lvl2",
    "categories.lvl3",
  ],
});

limit

number

default:10

How many facet values to retrieve. When you enable the showMore feature, this is the number of facet values to display before clicking the “Show more” button.

JavaScript

hierarchicalMenu({
  // ...
  limit: 5,
});

showMore

boolean

default:false

Whether to display a button that expands the number of items.

JavaScript

hierarchicalMenu({
  // ...
  showMore: true,
});

showMoreLimit

number

The maximum number of displayed items (only used when showMore is set to true).

JavaScript

hierarchicalMenu({
  // ...
  showMoreLimit: 20,
});

separator

string

default:">"

The level separator used in the records.

JavaScript

hierarchicalMenu({
  // ...
  separator: " / ",
});

rootPath

string

default:"null"

The prefix path to use if the first level is not the root level.Make sure to also include the root path in your UI state, for example, by setting initialUiState or calling setUiState().

JavaScript

instantsearch({
  // ...
  initialUiState: {
    YourIndexName: {
      hierarchicalMenu: {
        "categories.lvl0": ["Computers & Tablets"],
      },
    },
  },
}).addWidgets([
  hierarchicalMenu({
    // ...
    rootPath: "Computers & Tablets",
  }),
]);

showParentLevel

boolean

default:true

Whether to show the siblings of the selected parent level of the current refined value.This option doesn’t impact the root level. All root items are always visible.

JavaScript

hierarchicalMenu({
  // ...
  showParentLevel: false,
});

sortBy

string[] | function

default:"Uses facetOrdering if set, ['name:asc']"

How to sort refinements. Must be one or more of the following strings:

"count" (same as "count:desc")
"count:asc"
"count:desc"
"name" (same as "name:asc")
"name:asc"
"name:desc"
"isRefined" (same as "isRefined:asc")
"isRefined:asc"
"isRefined:desc"

You can also give a function, which receives items two by two, like JavaScript’s Array.sort.

hierarchicalMenu({
  // ...
  sortBy: ['isRefined'],
});

templates

object

The templates to use for the widget.

JavaScript

hierarchicalMenu({
  // ...
  templates: {
    // ...
  },
});

cssClasses

object

default:"{}"

The CSS classes you can override:

root. The root element of the widget.
noRefinementRoot. The root element if there are no refinements.
list. The list of results.
childList. The child list element.
item. The list items.
selectedItem. The selected item of the list.
parentItem. The parent item of the list.
link. The link of each item.
selectedItemLink. The link of each selected item.
label. The label of each item.
count. The count of each item.
showMore. The “Show more” button.
disabledShowMore. The disabled “Show more” button.

JavaScript

hierarchicalMenu({
  // ...
  cssClasses: {
    root: "MyCustomHierarchicalMenu",
    list: [
      "MyCustomHierarchicalMenuList",
      "MyCustomHierarchicalMenuList--subclass",
    ],
  },
});

transformItems

function

default:"items => items"

A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

hierarchicalMenu({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

// or, combined with results
hierarchicalMenu({
  // ...
  transformItems(items, { results }) {
    return items.map((item) => ({
      ...item,
      label: item.isRefined
        ? `${item.label} (page ${results.page + 1}/${results.nbPages})`
        : item.label,
    }));
  },
});

Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

item

string | function

The template for each item. It exposes:

label: string. The label of the item.
value: string. The value of the item.
count: number. The number of results matching the value.
isRefined: boolean Whether the item is selected.
url: string. The URL with the applied refinement.

hierarchicalMenu({
  // ...
  templates: {
    item(data, { html }) {
      return html`
        <a class="${data.cssClasses.link}" href="${data.url}">
          <span class="${data.cssClasses.label}">${data.label}</span>
          <span class="${data.cssClasses.count}">
            ${data.count.toLocaleString()}
          </span>
        </a>
      `;
    },
  },
});

showMoreText

string | function

The template for the “Show more” button text. It exposes:

isShowingMore: boolean. Whether the list is expanded.

hierarchicalMenu({
  // ...
  templates: {
    showMoreText(data, { html }) {
      return html`<span>${data.isShowingMore ? 'Show less' : 'Show more'}</span>`;
    },
  },
});

HTML output

HTML

<div class="ais-HierarchicalMenu">
  <ul class="ais-HierarchicalMenu-list ais-HierarchicalMenu-list--lvl0">
    <li
      class="ais-HierarchicalMenu-item ais-HierarchicalMenu-item--parent ais-HierarchicalMenu-item--selected"
    >
      <a
        class="ais-HierarchicalMenu-link ais-HierarchicalMenu-link--selected"
        href="#"
      >
        <span class="ais-HierarchicalMenu-label">Appliances</span>
        <span class="ais-HierarchicalMenu-count">4,306</span>
      </a>
      <ul
        class="ais-HierarchicalMenu-list ais-HierarchicalMenu-list--child ais-HierarchicalMenu-list--lvl1"
      >
        <li class="ais-HierarchicalMenu-item ais-HierarchicalMenu-item--parent">
          <a class="ais-HierarchicalMenu-link" href="#">
            <span class="ais-HierarchicalMenu-label">Dishwashers</span>
            <span class="ais-HierarchicalMenu-count">181</span>
          </a>
        </li>
        <li class="ais-HierarchicalMenu-item">
          <a class="ais-HierarchicalMenu-link" href="#">
            <span class="ais-HierarchicalMenu-label">Fans</span>
            <span class="ais-HierarchicalMenu-count">91</span>
          </a>
        </li>
      </ul>
    </li>
    <li class="ais-HierarchicalMenu-item ais-HierarchicalMenu-item--parent">
      <a class="ais-HierarchicalMenu-link" href="#">
        <span class="ais-HierarchicalMenu-label">Audio</span>
        <span class="ais-HierarchicalMenu-count">1,570</span>
      </a>
    </li>
  </ul>
  <button class="ais-HierarchicalMenu-showMore">Show more</button>
</div>

Customize the UI with `connectHierarchicalMenu`

If you want to create your own UI of the hierarchicalMenu widget, you can use connectors. To use connectHierarchicalMenu, you can import it with the declaration relevant to how you installed InstantSearch.js.

import { connectHierarchicalMenu } from 'instantsearch.js/es/connectors';

Then it’s a 3-step process:

JavaScript

// 1. Create a render function
const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customHierarchicalMenu = connectHierarchicalMenu(renderHierarchicalMenu);

// 3. Instantiate
search.addWidgets([
  customHierarchicalMenu({
    // instance params
  }),
]);

Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

JavaScript

const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  const {
    items,
    isShowingMore,
    canToggleShowMore,
    canRefine,
    refine,
    sendEvent,
    toggleShowMore,
    createURL,
    widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
};

If SEO is important for your search page, ensure that your custom HTML is optimized for search engines:

Use <a> tags with href attributes to allow search engine bots to follow links.
Use semantic HTML and include structured data when relevant.

For more guidance, see the SEO checklist.

Rendering options

items

object[]

The list of available items, with each item:

label: string. The label of the item.
value: string. The value of the item.
count: number. The number results matching this value.
isRefined: boolean. Whether the item is selected.
data: object[]|null. The list of children for the current item.

JavaScript

const renderList = (items) => `
  <ul>
    ${items
      .map(
        (item) => `
          <li>
            <a href="#">${item.label} (${item.count})</a>
            ${item.data ? renderList(item.data) : ""}
          </li>
        `,
      )
      .join("")}
  </ul>
`;

const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

  const children = renderList(items);

  document.querySelector("#hierarchical-menu").innerHTML = children;
};

isShowingMore

boolean

Whether the list is expanded.

JavaScript

const renderList = (items) => `
  <ul>
    ${items
      .map(
        (item) => `
          <li>
            <a href="#">${item.label} (${item.count})</a>
            ${item.data ? renderList(item.data) : ""}
          </li>
        `,
      )
      .join("")}
  </ul>
`;

const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  const { items, isShowingMore } = renderOptions;

  document.querySelector("#hierarchical-menu").innerHTML = `
    ${renderList(items)}
    <button>${isShowingMore ? "Show less" : "Show more"}</button>
  `;
};

canToggleShowMore

boolean

Whether users can click the “Show more” button.

JavaScript

const renderList = (items) => `
  <ul>
    ${items
      .map(
        (item) => `
          <li>
            <a href="#">${item.label} (${item.count})</a>
            ${item.data ? renderList(item.data) : ""}
          </li>
        `,
      )
      .join("")}
  </ul>
`;

const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  const { items, canToggleShowMore } = renderOptions;

  document.querySelector("#hierarchical-menu").innerHTML =
    `  ${renderList(items)}
    <button ${!canToggleShowMore ? "disabled" : ""}>Show more</button>`;
};

canRefine

boolean

required

Indicates if search state can be refined.

JavaScript

const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  const { items, canRefine } = renderOptions;

  if (!canRefine) {
    document.querySelector("#hierarchical-menu").innerHTML = "";
    return;
  }
};

refine

function

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

JavaScript

const renderList = (items) => `
  <ul>
    ${items
      .map(
        (item) => `
          <li>
            <a
              href="#"
              data-value="${item.value}"
              style="font-weight: ${item.isRefined ? "bold" : ""}"
            >
              ${item.label} (${item.count})
            </a>
            ${item.data ? renderList(item.data) : ""}
          </li>
        `,
      )
      .join("")}
  </ul>
`;

const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  const { items, refine } = renderOptions;

  const container = document.querySelector("#hierarchical-menu");

  container.innerHTML = renderList(items);

  [...container.querySelectorAll("a")].forEach((element) => {
    element.addEventListener("click", (event) => {
      event.preventDefault();
      refine(event.target.dataset.value);
    });
  });
};

sendEvent

(eventType, facetValue) => void

The function to send click events.

The view event is automatically sent when the facets are rendered.
The click event is automatically sent when refine is called.
You can learn more about the insights middleware.
eventType: 'click'
facetValue: string

JavaScript

// For example,
sendEvent('click', 'Laptop');

/*
  A payload like the following will be sent to the `insights` middleware.
  {
    eventType: 'click',
    insightsMethod: 'clickedFilters',
    payload: {
      eventName: 'Filter Applied',
      filters: ['category:"Laptop"'],
      index: '<index-name>',
    },
    widgetType: 'ais.hierarchicalMenu',
  }
*/

toggleShowMore

function

Toggles the number of displayed values between limit and showMoreLimit.

JavaScript

const renderList = (items) => `
  <ul>
    ${items
      .map(
        (item) => `
          <li>
            <a href="#">${item.label} (${item.count})</a>
            ${item.data ? renderList(item.data) : ""}
          </li>
        `,
      )
      .join("")}
  </ul>
`;

const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  const { items, isShowingMore, toggleShowMore } = renderOptions;

  const container = document.querySelector("#hierarchical-menu");

  if (isFirstRender) {
    const list = document.createElement("div");
    const button = document.createElement("button");

    button.addEventListener("click", () => {
      toggleShowMore();
    });

    container.appendChild(list);
    container.appendChild(button);
  }

  container.querySelector("div").innerHTML = renderList(items);
  container.querySelector("button").textContent = isShowingMore
    ? "Show less"
    : "Show more";
};

createURL

function

Generates a URL for the next state.

JavaScript

const renderList = ({ items, createURL }) => `
  <ul>
    ${items
      .map(
        (item) => `
          <li>
            <a href="${createURL(item.value)}">
              ${item.label} (${item.count})
            </a>
            ${item.data ? renderList({ items: item.data, createURL }) : ""}
          </li>
        `,
      )
      .join("")}
  </ul>
`;

const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  const { items, createURL } = renderOptions;

  const children = renderList({ items, createURL });

  document.querySelector("#hierarchical-menu").innerHTML = children;
};

All original widget options are forwarded to the render function.

JavaScript

const renderHierarchicalMenu = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = '...';
};

// ...

search.addWidgets([
  customHierarchicalMenu({
    // ...
    container: document.querySelector('#hierarchical-menu'),
  })
]);

First, create your custom widgets using a rendering function. Then, instantiate them with parameters. There are two kinds of parameters you can pass:

Instance parameters. Predefined options that configure Algolia’s behavior.
Custom parameters. Parameters you define to make the widget reusable and adaptable.

Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.

JavaScript

const customHierarchicalMenu = connectHierarchicalMenu(
  renderHierarchicalMenu
);

search.addWidgets([
  customHierarchicalMenu({
    attributes: string[],
    // Optional parameters
    limit?: number,
    showMoreLimit?: number,
    separator?: string,
    rootPath?: string,
    showParentLevel?: boolean,
    sortBy?: string[] | function,
    transformItems?: function,
  })
]);

Instance options

attributes

string[]

required

The name of the attributes to generate the menu with.To avoid unexpected behavior, you can’t use the same attribute prop in a different type of widget.

JavaScript

customHierarchicalMenu({
  attributes: [
    "categories.lvl0",
    "categories.lvl1",
    "categories.lvl2",
    "categories.lvl3",
  ],
});

limit

number

default:10

The number of facet values to retrieve. When isShowingMore is false, this is the number of facet values displayed before clicking the “Show more” button.

JavaScript

customHierarchicalMenu({
  // ...
  limit: 5,
});

showMoreLimit

number

The maximum number of displayed items (only used when the showMore feature is implemented).

JavaScript

customHierarchicalMenu({
  // ...
  showMoreLimit: 20,
});

separator

string

default:">"

The level separator used in the records.

JavaScript

customHierarchicalMenu({
  // ...
  separator: " / ",
});

rootPath

string

The prefix path to use if the first level is not the root level.Make sure to also include the root path in your UI state, for example, by setting initialUiState or calling setUiState().

JavaScript

customHierarchicalMenu({
  // ...
  rootPath: "Computers & Tablets",
});

showParentLevel

boolean

default:true

Whether to show the siblings of the selected parent level of the current refined value.

JavaScript

customHierarchicalMenu({
  // ...
  showParentLevel: false,
});

sortBy

string[] | function

default:"Uses facetOrdering if set, ['name:asc']"

How to sort refinements. Must be one or more of the following strings:

"count:asc"
"count:desc"
"name:asc"
"name:desc"
"isRefined"

You can also give a function that receives items two by two, like JavaScript’s Array.sortIf facetOrdering is set for this facet in renderingContent, and no value for sortBy is passed to this widget, facetOrdering is used, and the default order as a fallback.

customHierarchicalMenu({
  // ...
  sortBy: ['isRefined'],
});

transformItems

function

default:"items => items"

JavaScript

customHierarchicalMenu({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

/* or, combined with results */
customHierarchicalMenu({
  // ...
  transformItems(items, { results }) {
    return items.map((item) => ({
      ...item,
      label: item.isRefined
        ? `${item.label} (page ${results.page + 1}/${results.nbPages})`
        : item.label,
    }));
  },
});

Full example

<div id="hierarchical-menu"></div>

InstantSearch.js

hierarchicalMenu

Import

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectHierarchicalMenu`

Create a render function

Rendering options

Create and instantiate the custom widget

Instance options

Full example

InstantSearch.js

​Import

​About this widget

​Requirements

​Examples

​Options

​Templates

​HTML output

​Customize the UI with connectHierarchicalMenu

​Create a render function

​Rendering options

​Create and instantiate the custom widget

​Instance options

​Full example

Import

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectHierarchicalMenu`

Create a render function

Rendering options

Create and instantiate the custom widget

Instance options

Full example