> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# menuSelect
> Lets users refine search results using a drop-down menu.
export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => {
if (options.length === 0) {
return
```ts Signature theme={"system"}
menuSelect({
container: string | HTMLElement,
attribute: string,
// Optional parameters
limit?: number,
sortBy?: string[] | function,
templates?: object,
cssClasses?: object,
transformItems?: function,
});
```
## Import
```js Package manager theme={"system"}
import { menuSelect } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { menuSelect } = instantsearch.widgets;
// or directly use instantsearch.widgets.menuSelect()
```
Preview this widget and its behavior.
## About this widget
The `menuSelect` widget allows a user to select a single value to refine inside a [`select`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select) element.
### 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"}
menuSelect({
container: "#menu-select",
attribute: "brand",
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
menuSelect({
// ...
container: "#menu-select",
});
```
```js HTMLElement theme={"system"}
menuSelect({
// ...
container: document.querySelector("#menu-select"),
});
```
The name of the attribute in the record.
```js JavaScript icon=code theme={"system"}
menuSelect({
// ...
attribute: "brand",
});
```
The maximum number of values to display.
```js JavaScript icon=code theme={"system"}
menuSelect({
// ...
limit: 20,
});
```
How to sort refinements. Must be one or more of the following strings:
* `"count:asc"`
* `"count:desc"`
* `"name:asc"`
* `"name:desc"`
* `"isRefined"`
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"}
menuSelect({
// ...
sortBy: ["isRefined"],
});
```
```js function theme={"system"}
menuSelect({
// ...
sortBy(a, b) {
return a.name < b.name ? 1 : -1;
},
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
menuSelect({
// ...
templates: {
// ...
},
});
```
TThe [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.
* `select`. The `select` element.
* `option`. The `option` elements of the `select`.
```js JavaScript icon=code theme={"system"}
menuSelect({
// ...
cssClasses: {
root: "MyCustomMenuSelect",
select: [
"MyCustomMenuSelectElement",
"MyCustomMenuSelectElement--subclass",
],
},
});
```
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"}
menuSelect({
// ...
transformItems(items) {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
},
});
```
## 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.
The template to customize each `option` element. It exposes:
* `label: string`. The label to display in the option.
* `value: string`. The value for the option.
* `count: number`. The number of hits that match this value.
* `isRefined: boolean`. Indicates if it's the current refined value.
```js function theme={"system"}
menuSelect({
// ...
templates: {
item(item, { html }) {
return html`${item.label} - (${item.count.toLocaleString()})`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
menuSelect({
// ...
templates: {
item: "{{label}} ({{#helpers.formatNumber}}{{count}}{{/helpers.formatNumber}})",
},
});
```
The template to customize the first option of the select.
```js function theme={"system"}
menuSelect({
// ...
templates: {
defaultOption(data, { html }) {
return html`See all`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
menuSelect({
// ...
templates: {
defaultOption: "See all",
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
```
## Customize the UI with `connectMenu`
If you want to create your own UI of the `menuSelect` widget, you can use connectors.
This connector is also used to build the [`menu`](/doc/api-reference/widgets/menu/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 renderMenuSelect = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customMenuSelect = connectMenu(renderMenuSelect);
// 3. Instantiate
search.addWidgets([
customMenuSelect({
// 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).
```js JavaScript icon=code theme={"system"}
const renderMenuSelect = (renderOptions, isFirstRender) => {
const { items, canRefine, refine, sendEvent, 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).
#### Rendering 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 matched results after a refinement is applied.
* `isRefined: boolean`. Indicates if the refinement is applied.
```js JavaScript icon=code theme={"system"}
const renderMenuSelect = (renderOptions, isFirstRender) => {
const { items } = renderOptions;
document.querySelector("#menu-select").innerHTML = `
`;
};
```
Returns `true` if a refinement can be applied.
```js JavaScript icon=code theme={"system"}
const renderMenuSelect = (renderOptions, isFirstRender) => {
const { items, canRefine } = renderOptions;
document.querySelector("#menu-select").innerHTML = `
`;
};
```
Sets the refinement and triggers a search.
```js JavaScript icon=code theme={"system"}
const renderMenuSelect = (renderOptions, isFirstRender) => {
const { items, refine } = renderOptions;
const container = document.querySelector("#menu-select");
if (isFirstRender) {
const select = document.createElement("select");
select.addEventListener("change", (event) => {
refine(event.target.value);
});
container.appendChild(select);
}
container.querySelector("select").innerHTML = `
${items
.map(
(item) =>
``,
)
.join("")}
`;
};
```
The function to send `click` events.
The `click` event is automatically sent when `refine` is called.
To learn more, see the [`insights`](/doc/api-reference/widgets/insights/js) 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',
}
*/
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
const renderMenuSelect = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = "...";
};
// ...
search.addWidgets([
customMenuSelect({
container: document.querySelector("#menu-select"),
}),
]);
```
### 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`.
```jsx JavaScript icon=code theme={"system"}
const customMenuSelect = connectMenu(
renderMenuSelect
);
search.addWidgets([
customMenuSelect({
attribute: string,
// Optional parameters
limit: number,
sortBy: string[] | function,
transformItems: function,
})
]);
```
#### Instance options
The name of the attribute in the record.
```js JavaScript icon=code theme={"system"}
customMenuSelect({
attribute: "brand",
});
```
The maximum number of values to display.
```js JavaScript icon=code theme={"system"}
customMenuSelect({
// ...
limit: 20,
});
```
How to sort refinements. Must be one or more of the following strings:
* `"count:asc"`
* `"count:desc"`
* `"name:asc"`
* `"name:desc"`
* `"isRefined"`
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).
```js string[] theme={"system"}
customMenuSelect({
// ...
sortBy: ["name:asc"],
});
```
```js function theme={"system"}
customMenuSelect({
// ...
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"}
customMenuSelect({
// ...
transformItems(items) {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
},
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// Create the render function
const renderMenuSelect = (renderOptions, isFirstRender) => {
const { items, canRefine, refine, widgetParams } = renderOptions;
if (isFirstRender) {
const select = document.createElement("select");
select.addEventListener("change", (event) => {
refine(event.target.value);
});
widgetParams.container.appendChild(select);
}
const select = widgetParams.container.querySelector("select");
select.disabled = !canRefine;
select.innerHTML = `
${items
.map(
(item) =>
``,
)
.join("")}
`;
};
// Create the custom widget
const customMenuSelect = connectMenu(renderMenuSelect);
// Instantiate the custom widget
search.addWidgets([
customMenuSelect({
container: document.querySelector("#menu-select"),
attribute: "brand",
}),
]);
```