` prop to forward to the root element of the widget.
```jsx JavaScript icon=code theme={"system"}
;
```
## Hook
React InstantSearch let you create your own UI for the `
` widget with `useMenu`.
Hooks provide APIs to access the widget state and interact with InstantSearch.
The `useMenu` 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 { useMenu } from "react-instantsearch";
function CustomMenu(props) {
const {
items,
createURL,
refine,
canRefine,
isShowingMore,
toggleShowMore,
canToggleShowMore,
sendEvent,
} = useMenu(props);
return <>{/*Your JSX*/};
}
```
Then, render the widget:
```jsx JavaScript icon=code theme={"system"}
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 name of the attribute in 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 menuApi = useMenu({
attribute: "categories",
});
```
How many facet values to retrieve.
[`showMore`](#param-show-more) and [`showMoreLimit`](#param-show-more-limit) determine the number of facet values to display before clicking the Show more button.
```jsx JavaScript icon=code theme={"system"}
const menuApi = useMenu({
// ...
limit: 5,
});
```
Whether to display a button that expands the number of items.
```jsx JavaScript icon=code theme={"system"}
const menuApi = useMenu({
// ...
showMore: true,
});
```
The maximum number of items to display if the widget is showing more than the [`limit`](#param-limit) items.
```jsx JavaScript icon=code theme={"system"}
const menuApi = useMenu({
// ...
showMoreLimit: 20,
});
```
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).
If you leave the default setting for 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 String theme={"system"}
const menuApi = useMenu({
// ...
sortBy: ["count:desc", "name:asc"],
});
```
```jsx Function theme={"system"}
const sortByName = (a, b) => {
return a.name.toLocaleLowerCase() < b.name.toLocaleLowerCase() ? -1 : 1;
};
function Menu() {
const menuApi = useMenu({
// ...
sortBy,
});
return <>{/* Your JSX */};
}
```
```tsx Function (TypeScript) theme={"system"}
import type { UseMenuProps } from "react-instantsearch";
const sortByName: UseMenuProps["sortBy"] = (a, b) => {
return a.name.toLocaleLowerCase() < b.name.toLocaleLowerCase() ? -1 : 1;
};
function Menu() {
const menuApi = useMenu({
// ...
sortBy,
});
return <>{/* Your JSX */};
}
```
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 Menu() {
const menuApi = useMenu({
// ...
transformItems,
});
return <>{/*Your JSX*/};
}
```
```tsx TypeScript theme={"system"}
import type { UseMenuProps } from 'react-instantsearch';
const transformItems: UseMenuProps['transformItems'] = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function Menu() {
const menuApi = useMenu({
// ...
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 elements that can be refined for the current search results.
```ts theme={"system"}
type MenuItem = {
/**
* The 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 menu item is refined.
*/
isRefined: boolean;
};
```
Creates the next state URL of a selected refinement.
Applies the selected refinement.
Whether a refinement can be applied.
Whether the menu is displaying all the menu items.
Toggles the number of values displayed between [`limit`](/doc/api-reference/widgets/menu/react#param-limit)
and [`showMoreLimit`](/doc/api-reference/widgets/menu/react#param-show-more-limit).
Whether the Show more button can be activated, meaning there are enough
additional items to display, or already displaying over the
[`limit`](/doc/api-reference/widgets/menu/react#param-limit) items.
Sends an event to the Insights middleware.
### Example
```jsx JavaScript theme={"system"}
import React from "react";
import { useMenu } from "react-instantsearch";
function CustomMenu(props) {
const {
items,
refine,
createURL,
canToggleShowMore,
toggleShowMore,
isShowingMore,
} = useMenu(props);
return (
<>
{props.showMore && (
{isShowingMore ? "Show less" : "Show more"}
)}
);
}
```
```tsx TypeScript theme={"system"}
import React from 'react';
import { useMenu, UseMenuProps } from 'react-instantsearch';
function CustomMenu(props: UseMenuProps) {
const {
items,
refine,
createURL,
canToggleShowMore,
toggleShowMore,
isShowingMore,
} = useMenu(props);
return (
<>
{props.showMore && (
{isShowingMore ? 'Show less' : 'Show more'}
)}
);
}
```