API Reference / React InstantSearch Hooks / <HierarchicalMenu>

<HierarchicalMenu>

A
Signature 
<HierarchicalMenu
  attributes={string[]}
  // Optional props
  limit={number}
  showMore={boolean}
  showMoreLimit={number}
  separator={string}
  rootPath={string}
  showParentLevel={boolean}
  sortBy={string[] | Function}
  transformItems={(items: HierarchicalMenuItem[]) => HierarchicalMenuItem[]}
  classNames={Partial<HierarchicalMenuClassNames>}
  ...props={React.ComponentProps<'div'>}
/>
See code examples
See live example

About this widget # A

<HierarchicalMenu> is a widget that creates a navigation based on a hierarchy of facet attributes. It’s commonly used for categories with subcategories.

Requirements#

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

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

It’s also possible to provide more than one path for each level:

Copy 
1
2
3
4
5
6
7
8

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

The attributes provided to the widget must be in attributes for faceting, either on the dashboard or using attributesForFaceting with the API. By default, the separator is > (with spaces) but you can use a different one by using the separator option.

You can also create your own UI with useHierarchicalMenu().

Examples # A

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, HierarchicalMenu } from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <HierarchicalMenu
        attributes={[
          'hierarchicalCategories.lvl0',
          'hierarchicalCategories.lvl1',
          'hierarchicalCategories.lvl2',
          'hierarchicalCategories.lvl3',
        ]}
      />
    </InstantSearch>
  );
}

Props # A

attributes #
type: string[]
Required

The name of the attributes to generate the menu with.
Copy 
1
2
3
4
5
6
7
8

<HierarchicalMenu
  attributes={[
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
    'hierarchicalCategories.lvl3',
  ]}
/>
limit #
type: 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.
Copy 
1
2
3
4

<HierarchicalMenu
  // ...
  limit={5}
/>
showMore #
type: boolean
default: false

Whether to display a button that expands the number of items.
Copy 
1
2
3
4

<HierarchicalMenu
  // ...
  showMore={true}
/>
showMoreLimit #
type: number

The maximum number of displayed items (only used when showMore is set to true).
Copy 
1
2
3
4

<HierarchicalMenu
  // ...
  showMoreLimit={20}
/>
separator #
type: string
default: " > "

The level separator used in the records.
Copy 
1
2
3
4

<HierarchicalMenu
  // ...
  separator=" / "
/>
rootPath #
type: string

The prefix path to use if the first level isn’t the root level.
Copy 
1
2
3
4

<HierarchicalMenu
  // ...
  rootPath="Computers & Tablets"
/>
showParentLevel #
type: boolean
default: true

Whether to show the siblings of the selected parent level of the current refined value.
Copy 
1
2
3
4

<HierarchicalMenu
  // ...
  showParentLevel={false}
/>
sortBy #
type: string[] | (a: RefinementListItem, b: RefinementListItem) => number
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"

It’s also possible to give a function, which receives items two by two, like JavaScript’s Array.sort.
Copy 
1
2
3
4

<HierarchicalMenu
  // ...
  sortBy={['isRefined']}
/>
transformItems #
type: UseRefinementListProps['transformItems']

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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

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

CSS classes to pass to the widget’s elements. This is useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

  • root: The root element of the widget.
  • noRefinementRoot: The root element when there are no refinements.
  • list: The list element.
  • item: Each item element.
  • selectedItem: The selected item element.
  • parentItem: The parent item of the list.
  • link: The link of each item.
  • label: The label of each item.
  • count: The count of each item.
  • showMore: The “Show more” button.
  • disabledShowMore: The disabled “Show more” button.
Copy 
1
2
3
4
5
6
7

<HierarchicalMenu
  // ...
  classNames={{
    root: 'MyCustomHierarchicalMenu',
    list: 'MyCustomHierarchicalMenuList MyCustomHierarchicalMenuList--subclass',
  }}
/>
...props #
type: React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.
Copy 
1

<HierarchicalMenu className="MyCustomHierarchicalMenu" title="My custom title" />

Hook# A

React InstantSearch Hooks let you create your own UI for the <HierarchicalMenu> widget with useHierarchicalMenu(). Hooks provide APIs to access the widget state and interact with InstantSearch.

The useHierarchicalMenu() Hook accepts parameters and returns APIs.

See code examples

Usage#

First, create your React component:

import { useHierarchicalMenu } from 'react-instantsearch-hooks-web';
  
function CustomHierarchicalMenu(props) {
  const {
    items,
    isShowingMore,
    canToggleShowMore,
    canRefine,
    refine,
    sendEvent,
    toggleShowMore,
    createURL,
  } = useHierarchicalMenu(props);

  return <>{/* Your JSX */}</>;
}

Then, render the widget:

<CustomHierarchicalMenu {...props} />

Parameters#

Hooks accept parameters. You can pass them manually, or forward the props from your custom component.

When you provide a function to Hooks, make sure to pass a stable reference with useCallback() to avoid rendering endlessly. Objects and arrays are memoized so you don’t have to stabilize them.

attributes #
type: string[]
Required

The names of the attributes inside the records.
Copy 
1
2
3
4
5
6
7
8

const hierarchicalMenuApi = useHierarchicalMenu({
  attributes: [
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ],
});
separator #
type: string
default: " > "

The level separator used in the records.
Copy 
1
2
3
4

const hierarchicalMenuApi = useHierarchicalMenu({
  // ...
  separator: ' - ',
});
rootPath #
type: string

The path to use if the first level isn’t the root level.
Copy 
1
2
3
4

const hierarchicalMenuApi = useHierarchicalMenu({
  // ...
  rootPath: 'Audio > Home Audio',
});
showParentLevel #
type: boolean
default: true

Whether to show the siblings of the selected parent level of the current refined value.
Copy 
1
2
3
4

const hierarchicalMenuApi = useHierarchicalMenu({
  // ...
  showParentLevel: false,
});
limit #
type: 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.
Copy 
1
2
3
4

const hierarchicalMenuApi = useHierarchicalMenu({
  // ...
  limit: 5,
});
showMore #
type: boolean
default: false

Whether to display a button that expands the number of items.
Copy 
1
2
3
4

const hierarchicalMenuApi = useHierarchicalMenu({
  // ...
  showMore: true,
});
showMoreLimit #
type: number

The maximum number of displayed items. Only used when showMore is set to true.
Copy 
1
2
3
4

const hierarchicalMenuApi = useHierarchicalMenu({
  // ...
  showMoreLimit: 30,
});
sortBy #
type: string[] | (a: RefinementListItem, b: RefinementListItem) => number
default: ["name:asc"] (or `facetOrdering` if set)

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 use a sort function that behaves like the standard Javascript compareFunction.

When you don’t set this parameter, and you’ve set facetOrdering for this facet in renderingContent, facets are sorted using facetOrdering and use the default order as a fallback.
Copy 
1
2
3
4

const hierarchicalMenuApi = useHierarchicalMenu({
  // ...
  sortBy: ['count', 'name:asc'],
});
transformItems #
type: UseHierarchicalMenuProps['transformItems']

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

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

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

APIs#

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

items #
type: HierarchicalMenuItem[]

The list of items the widget can display.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

type HierarchicalMenuItem = {
  /**
  * Value of the menu item.
  */
  value: string;
  /**
  * Human-readable value of the menu item.
  */
  label: string;
  /**
  * Number of matched results after refinement is applied.
  */
  count: number;
  /**
  * Indicates if the refinement is applied.
  */
  isRefined: boolean;
  /**
  * n+1 level of items
  */
  data: HierarchicalMenuItem[] | null;
};
isShowingMore #
type: boolean

Whether the list is expanded.
canToggleShowMore #
type: boolean

Whether the “Show more” button can be clicked.
canRefine #
type: boolean

Indicates if search state can be refined.
refine #
type: (value: string) => void

Sets the path of the hierarchical filter and triggers a new search.
sendEvent #
type: (eventType: string, facetValue: string, eventName?: string) => 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
toggleShowMore #
type: () => void

Toggles the number of displayed values between limit and showMoreLimit.
createURL #
type: (value: string) => string

Generates a URL for the next state.

Example#

Copy 
1
2
3
4
5
6
7
8

import React from 'react';
import { useHierarchicalMenu } from 'react-instantsearch-hooks-web';

function CustomHierarchicalMenu(props) {
  const { items, refine } = useHierarchicalMenu(props);

  return <>{/* Your JSX */}</>;
}
Did you find this page helpful?
React InstantSearch Hooks v6