> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# menu
> Shows a menu for refining search results based on a selected facet value.
export const Records = () =>
records
;
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
FlavorSwitcher requires at least one option.
;
}
const selected = options.find(option => option.value === current) ?? options[0];
return ;
};
```ts Signature theme={"system"}
menu({
container: string | HTMLElement,
attribute: string,
// Optional parameters
limit?: number,
showMore?: boolean,
showMoreLimit?: number,
sortBy?: string[] | function,
templates?: object,
cssClasses?: object,
transformItems?: function,
});
```
## Import
```js Package manager theme={"system"}
import { menu } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { menu } = instantsearch.widgets;
// or directly use instantsearch.widgets.menu()
```
Preview this widget and its behavior.
## About this widget
The `menu` widget displays a menu that lets users choose a single value for a specific attribute.
The `menu` widget uses a hierarchical refinement internally, so it can't refine values that include the default separator (`>`).
To support these values, use the [`hierarchicalMenu`](/doc/api-reference/widgets/hierarchical-menu/js) widget instead.
### Requirements
The [`attribute`](#param-attribute) provided to the widget must be in attributes for faceting,
either on the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or using the [`attributesForFaceting`](/doc/api-reference/api-parameters/attributesForFaceting) parameter with the API.
## Examples
```js JavaScript icon=code theme={"system"}
menu({
container: "#menu",
attribute: "categories",
});
```
## Options
The CSS Selector of the DOM element inside which the widget is inserted.
```js string theme={"system"}
menu({
// ...
container: "#menu",
});
```
```js HTMLElement theme={"system"}
menu({
// ...
container: document.querySelector("#menu"),
});
```
The name of the attribute in the .
To avoid unexpected behavior, you can't use the same `attribute` prop in a different type of widget.
```js JavaScript icon=code theme={"system"}
menu({
// ...
attribute: "categories",
});
```
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.
```js JavaScript icon=code theme={"system"}
menu({
// ...
limit: 20,
});
```
Limits the number of results and display a `showMore` button.
```js boolean theme={"system"}
menu({
// ...
showMore: true,
});
```
How many facet values to retrieve when showing more.
```js JavaScript icon=code theme={"system"}
menu({
// ...
showMoreLimit: 30,
});
```
How to sort refinements. Must be one 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"`
**Default:** `["isRefined", "name:asc"]`
It's also possible to give a function, which receives items two by two, like JavaScript's [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).
If `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.
```js string[] theme={"system"}
menu({
// ...
sortBy: ["count:desc", "name:asc"],
});
```
```js function theme={"system"}
menu({
// ...
sortBy(a, b) {
return a.name < b.name ? 1 : -1;
},
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
menu({
// ...
templates: {
// ...
},
});
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):
* `root`. The root element of the widget.
* `noRefinementRoot`. The root element if there are no refinements.
* `list`. The list of results.
* `item`. The list items. They contain the link and separator.
* `selectedItem`. The selected item in the list. This is the last one, or the root one if there are no refinements.
* `link`. The link element of each item.
* `label`. The label element of each item.
* `count`. The count element of each item.
* `showMore`. The "Show more" button.
* `disabledShowMore`. The "Show more" button when disabled.
```js JavaScript icon=code theme={"system"}
menu({
// ...
cssClasses: {
root: "MyCustomMenu",
list: ["MyCustomMenuList", "MyCustomMenuList--sub-class"],
},
});
```
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`.
```js JavaScript icon=code theme={"system"}
menu({
// ...
transformItems(items) {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
},
});
// or: combined with results
menu({
// ...
transformItems(items, { results }) {
return items.map((item) => ({
...item,
label: item.isRefined
? `${item.label} (${results.nbPages} pages)`
: 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
Item template. It exposes:
* `count`. The number of occurrences of the facet in the result set.
* `isRefined`. Returns `true` if the value is selected.
* `label`. The label to display.
* `value`. The value used for refining.
* `url`. The URL with the selected refinement.
* `cssClasses`. An object containing all the computed classes for the item.
```js function theme={"system"}
menu({
// ...
templates: {
item(data, { html }) {
const { label, count, url, cssClasses } = data;
return html`
${label}
${count.toLocaleString()}
`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
menu({
// ...
templates: {
item: `
{{label}}
{{#helpers.formatNumber}}{{count}}{{/helpers.formatNumber}}
`,
},
});
```
The template for the "Show more" button text. It exposes:
* `isShowingMore: boolean`. Whether the list is expanded.
```js function theme={"system"}
menu({
// ...
templates: {
showMoreText(data, { html }) {
return html`${data.isShowingMore ? "Show less" : "Show more"}`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
menu({
// ...
templates: {
showMoreText: `
{{#isShowingMore}}
Show less
{{/isShowingMore}}
{{^isShowingMore}}
Show more
{{/isShowingMore}}
`,
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## Customize the UI with `connectMenu`
If you want to create your own UI of the `menu` widget, you can use connectors.
This connector is also used to build the [`menuSelect`](/doc/api-reference/widgets/menu-select/js) widget.
To use `connectMenu`, you can import it with the declaration relevant to how you installed InstantSearch.js.
```js Package manager theme={"system"}
import { connectMenu } from 'instantsearch.js/es/connectors';
```
```js CDN theme={"system"}
const { connectMenu } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectMenu()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 1. Create a render function
const renderMenu = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customMenu = connectMenu(renderMenu);
// 3. Instantiate
search.addWidgets([
customMenu({
// Widget parameters
}),
]);
```
### 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).
```js JavaScript icon=code theme={"system"}
const renderMenu = (renderOptions, isFirstRender) => {
const {
items,
canRefine,
refine,
sendEvent,
createURL,
isShowingMore,
canToggleShowMore,
toggleShowMore,
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 `` tags with `href` attributes to allow search engine bots to follow links.
* Use semantic HTML and include [structured data](https://developers.google.com/search/docs/appearance/structured-data) when relevant.
For more guidance, see the [SEO checklist](/doc/guides/building-search-ui/resources/seo/js).
#### Render options
The elements that can be refined for the current search results. With each item:
* `value: string`. The value of the menu item.
* `label: string`. The label of the menu item.
* `count: number`. The number of results matched after a refinement is applied.
* `isRefined: boolean`. Indicates if the refinement is applied.
```js JavaScript icon=code theme={"system"}
const renderMenu = (renderOptions, isFirstRender) => {
const { items } = renderOptions;
document.querySelector("#menu").innerHTML = `
`;
};
```
Indicates if search state can be refined.
```js JavaScript icon=code theme={"system"}
const renderMenu = (renderOptions, isFirstRender) => {
const { items, canRefine, refine } = renderOptions;
const container = document.querySelector("#menu");
if (!canRefine) {
container.innerHTML = "";
return;
}
};
```
A function to toggle a refinement.
```js JavaScript icon=code theme={"system"}
const renderMenu = (renderOptions, isFirstRender) => {
const { items, refine } = renderOptions;
const container = document.querySelector("#menu");
container.innerHTML = `
`;
[...container.querySelectorAll("a")].forEach((element) => {
element.addEventListener("click", (event) => {
event.preventDefault();
refine(event.currentTarget.dataset.value);
});
});
};
```
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 middleware.
* `eventType: 'click'`
* `facetValue: string`
```js JavaScript icon=code theme={"system"}
// For example,
sendEvent("click", "Apple");
/*
A payload like the following will be sent to the `insights` middleware.
{
eventType: 'click',
insightsMethod: 'clickedFilters',
payload: {
eventName: 'Filter Applied',
filters: ['brand:"Apple"'],
index: '',
},
widgetType: 'ais.menu',
}
*/
```
string"]}>
Generates a URL for the corresponding search state.
```js JavaScript icon=code theme={"system"}
const renderMenu = (renderOptions, isFirstRender) => {
const { items, createURL } = renderOptions;
document.querySelector("#menu").innerHTML = `
`;
};
```
Returns `true` if the menu is displaying all the menu items.
```js JavaScript icon=code theme={"system"}
const renderMenu = (renderOptions, isFirstRender) => {
const { items, isShowingMore, toggleShowMore } = renderOptions;
const container = document.querySelector("#menu");
if (isFirstRender) {
const ul = document.createElement("ul");
const button = document.createElement("button");
button.textContent = "Show more";
button.addEventListener("click", () => {
toggleShowMore();
});
container.appendChild(ul);
container.appendChild(button);
}
container.querySelector("ul").innerHTML = items
.map(
(item) => `
${item.label} (${item.count})
`,
)
.join("");
container.querySelector("button").textContent = isShowingMore
? "Show less"
: "Show more";
};
```
Returns `true` if the "Show more" button can be activated (enough items to display more and not already displaying more than [`limit`](/doc/api-reference/widgets/menu/js#param-limit) items).
```js JavaScript icon=code theme={"system"}
const renderMenu = (renderOptions, isFirstRender) => {
const { items, canToggleShowMore, toggleShowMore } = renderOptions;
const container = document.querySelector("#menu");
if (isFirstRender) {
const ul = document.createElement("ul");
const button = document.createElement("button");
button.textContent = "Show more";
button.addEventListener("click", () => {
toggleShowMore();
});
container.appendChild(ul);
container.appendChild(button);
}
container.querySelector("ul").innerHTML = items
.map(
(item) => `
${item.label} (${item.count})
`,
)
.join("");
container.querySelector("button").disabled = !canToggleShowMore;
};
```
Toggles the number of displayed values between [`limit`](/doc/api-reference/widgets/menu/js#param-limit) and [`showMoreLimit`](/doc/api-reference/widgets/menu/js#param-show-more-limit).
```js JavaScript icon=code theme={"system"}
const renderMenu = (renderOptions, isFirstRender) => {
const { items, toggleShowMore } = renderOptions;
const container = document.querySelector("#menu");
if (isFirstRender) {
const ul = document.createElement("ul");
const button = document.createElement("button");
button.textContent = "Show more";
button.addEventListener("click", () => {
toggleShowMore();
});
container.appendChild(ul);
container.appendChild(button);
}
container.querySelector("ul").innerHTML = items
.map(
(item) => `
${item.label} (${item.count})
`,
)
.join("");
};
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
const renderMenu = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = "...";
};
// ...
search.addWidgets([
customMenu({
// ...
container: document.querySelector("#menu"),
}),
]);
```
### Create and instantiate the custom widget
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`.
```js JavaScript icon=code theme={"system"}
const customMenu = connectMenu(renderMenu);
search.addWidgets([
customMenu({
attribute,
// Optional instance params
limit,
showMoreLimit,
sortBy,
transformItems,
}),
]);
```
#### Instance options
The name of the attribute for faceting.
To avoid unexpected behavior, you can't use the same `attribute` prop in a different type of widget.
```js JavaScript icon=code theme={"system"}
customMenu({
attribute: "categories",
});
```
How many facet values to retrieve. When you enable the
[`showMore`](/doc/api-reference/widgets/menu/js#param-show-more) feature, this is the number of facet
values to display before clicking the "Show more" button.
```js JavaScript icon=code theme={"system"}
customMenu({
// ...
limit: 20,
});
```
How many facet values to retrieve when showing more.
```js JavaScript icon=code theme={"system"}
customMenu({
// ...
showMoreLimit: 20,
});
```
How to sort refinements. Must be one or more of the following strings:
* `"count:asc"`
* `"count:desc"`
* `"name:asc"`
* `"name:desc"`
* `"isRefined"`
**Default:** `["isRefined", "name:asc"]`
It's also possible to give a function, which receives items two by two, like JavaScript's [`Array.sort`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).
If `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.
```js string[] theme={"system"}
customMenu({
// ...
sortBy: ["count:desc", "name:asc"],
});
```
```js function theme={"system"}
customMenu({
// ...
sortBy(a, b) {
return a.name < b.name ? 1 : -1;
},
});
```
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`.
```js JavaScript icon=code theme={"system"}
customMenu({
// ...
transformItems(items) {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
},
});
// or, combined with results
customMenu({
// ...
transformItems(items, { results }) {
return items.map((item) => ({
...item,
label: item.isRefined
? `${item.label} (${results.nbPages} pages)`
: item.label,
}));
},
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// 1. Create a render function
const renderMenu = (renderOptions, isFirstRender) => {
const {
items,
refine,
createURL,
isShowingMore,
canToggleShowMore,
toggleShowMore,
widgetParams,
} = renderOptions;
if (isFirstRender) {
const ul = document.createElement("ul");
const button = document.createElement("button");
button.textContent = "Show more";
button.addEventListener("click", () => {
toggleShowMore();
});
widgetParams.container.appendChild(ul);
widgetParams.container.appendChild(button);
}
widgetParams.container.querySelector("ul").innerHTML = items
.map(
(item) => `
${item.label} (${item.count})
`,
)
.join("");
[...widgetParams.container.querySelectorAll("a")].forEach((element) => {
element.addEventListener("click", (event) => {
event.preventDefault();
refine(event.currentTarget.dataset.value);
});
});
const button = widgetParams.container.querySelector("button");
button.disabled = !canToggleShowMore;
button.textContent = isShowingMore ? "Show less" : "Show more";
};
// 2. Create the custom widget
const customMenu = connectMenu(renderMenu);
// 3. Instantiate
search.addWidgets([
customMenu({
container: document.querySelector("#menu"),
attribute: "categories",
showMoreLimit: 20,
}),
]);
```