` prop to forward to the widget's root element. ```jsx JavaScript icon=code theme={"system"} ; ``` ## Hook React InstantSearch let you create your own UI for the `` widget with `useHierarchicalMenu`. Hooks provide APIs to access the widget state and interact with InstantSearch. The `useHierarchicalMenu` Hook accepts [parameters](#parameters) and returns [APIs](#hook). It must be used inside the [``](/doc/api-reference/widgets/instantsearch/react) component. ### Usage First, create your React component: ```jsx JavaScript icon=code theme={"system"} import { useHierarchicalMenu } from "react-instantsearch"; function CustomHierarchicalMenu(props) { const { items, isShowingMore, canToggleShowMore, canRefine, refine, sendEvent, toggleShowMore, createURL, } = useHierarchicalMenu(props); return <>{/*Your JSX*/}; } ``` Then, render the widget: ```jsx JavaScript icon=code theme={"system"} ; ``` ### Parameters Hooks accept parameters. You can either pass them manually or forward props from a custom component. When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization. Arrays and objects are automatically memoized. The names of the attributes inside the records. To avoid unexpected behavior, you can't use the same `attribute` prop in a different type of widget. ```jsx JavaScript icon=code theme={"system"} const hierarchicalMenuApi = useHierarchicalMenu({ attributes: [ "categories.lvl0", "categories.lvl1", "categories.lvl2", "categories.lvl3", ], }); ``` The level separator used in the records. ```jsx JavaScript icon=code theme={"system"} const hierarchicalMenuApi = useHierarchicalMenu({ // ... separator: " - ", }); ``` The path to use if the first level isn't the root level. Make sure to also include the root path in your [UI state](/doc/api-reference/widgets/ui-state/react), for example, by setting [`initialUiState`](/doc/api-reference/widgets/instantsearch/react#param-initial-ui-state) or calling [`setUiState`](/doc/api-reference/widgets/use-instantsearch/react#param-set-ui-state). ```jsx JavaScript icon=code theme={"system"} const hierarchicalMenuApi = useHierarchicalMenu({ // ... rootPath: "Audio > Home Audio", }); ``` Whether to show the siblings of the selected parent level of the current refined value. ```jsx JavaScript icon=code theme={"system"} const hierarchicalMenuApi = useHierarchicalMenu({ // ... showParentLevel: false, }); ``` How many facet values to retrieve. When you enable the [`showMore`](#param-show-more) feature, this is the number of facet values to display before clicking the Show more button. ```jsx JavaScript icon=code theme={"system"} const hierarchicalMenuApi = useHierarchicalMenu({ // ... limit: 5, }); ``` Whether to display a button that expands the number of items. ```jsx JavaScript icon=code theme={"system"} const hierarchicalMenuApi = useHierarchicalMenu({ // ... showMore: true, }); ``` The maximum number of displayed items. Only used when [`showMore`](#param-show-more) is set to `true`. ```jsx JavaScript icon=code theme={"system"} const hierarchicalMenuApi = useHierarchicalMenu({ // ... showMoreLimit: 30, }); ``` 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`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort#Syntax). 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. ```jsx JavaScript icon=code theme={"system"} const hierarchicalMenuApi = useHierarchicalMenu({ // ... sortBy: ["count", "name:asc"], }); ``` 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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/) and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters), such as `disjunctiveFacetsRefinements`. ```jsx JavaScript theme={"system"} const transformItems = (items) => { return items.map((item) => ({ ...item, label: item.label.toUpperCase(), })); }; function HierarchicalMenu() { const hierarchicalMenuApi = useHierarchicalMenu({ // ... transformItems, }); return <>{/* Your JSX */}; } ``` ```tsx TypeScript theme={"system"} import type { UseHierarchicalMenuProps } from 'react-instantsearch'; const transformItems: UseHierarchicalMenuProps['transformItems'] = (items) => { return items.map((item) => ({ ...item, label: item.label.toUpperCase(), })); }; function HierarchicalMenu() { const hierarchicalMenuApi = useHierarchicalMenu({ // ... transformItems, }); return <>{/* Your JSX */}; } ``` ### APIs Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch. The list of items the widget can display. ```ts TypeScript icon=code theme={"system"} 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; }; ``` Whether the list is expanded. Whether users can click the "Show more" button. Indicates if you can refine the search state. Sets the path of the hierarchical filter and triggers a new search. 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`](/doc/api-reference/widgets/insights/react) middleware. * `eventType: 'click'` * `facetValue: string` Toggles the number of displayed values between [`limit`](/doc/api-reference/widgets/hierarchical-menu/react#param-limit) and [`showMoreLimit`](/doc/api-reference/widgets/hierarchical-menu/react#param-show-more-limit). Generates a URL for the next state. ### Example ```jsx JavaScript theme={"system"} import React from "react"; import { useHierarchicalMenu } from "react-instantsearch"; function CustomHierarchicalMenu(props) { const { items, refine, canToggleShowMore, toggleShowMore, isShowingMore, createURL, } = useHierarchicalMenu(props); return ( <> {props.showMore && ( )} ); } function HierarchicalList({ items, createURL, onNavigate }) { if (items.length === 0) { return null; } return (

{ if (isModifierClick(event)) { return; } event.preventDefault(); onNavigate(item.value); }} style={{ fontWeight: item.isRefined ? "bold" : "normal" }} > {item.label} {item.count} {item.data && ( )}

); } function isModifierClick(event) { const isMiddleClick = event.button === 1; return Boolean( isMiddleClick || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey, ); } ``` ```tsx TypeScript theme={"system"} import React from "react"; import { useHierarchicalMenu, UseHierarchicalMenuProps, } from "react-instantsearch"; function CustomHierarchicalMenu(props: UseHierarchicalMenuProps) { const { items, refine, canToggleShowMore, toggleShowMore, isShowingMore, createURL, } = useHierarchicalMenu(props); return ( <> {props.showMore && ( )} ); } type HierarchicalListProps = Pick< ReturnType, "items" | "createURL" > & { onNavigate(value: string): void; }; function HierarchicalList({ items, createURL, onNavigate, }: HierarchicalListProps) { if (items.length === 0) { return null; } return (

{ if (isModifierClick(event)) { return; } event.preventDefault(); onNavigate(item.value); }} style={{ fontWeight: item.isRefined ? "bold" : "normal" }} > {item.label} {item.count} {item.data && ( )}

); } function isModifierClick(event: React.MouseEvent) { const isMiddleClick = event.button === 1; return Boolean( isMiddleClick || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey, ); } ```