> ## 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.

```ts Signature theme={"system"}
menuSelect({
  container: string | HTMLElement,
  attribute: string,
  // Optional parameters
  limit?: number,
  sortBy?: string[] | function,
  templates?: object,
  cssClasses?: object,
  transformItems?: function,
});
```

## Import

<CodeGroup>
  ```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()
  ```
</CodeGroup>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/js/?path=/story/refinements-menuselect--default" horizontal>
  Preview this widget and its behavior.
</Card>

## 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

<ParamField body="container" type="string | HTMLElement" required>
  The CSS Selector or `HTMLElement` to insert the widget into.

  <CodeGroup>
    ```js string theme={"system"}
    menuSelect({
      // ...
      container: "#menu-select",
    });
    ```

    ```js HTMLElement theme={"system"}
    menuSelect({
      // ...
      container: document.querySelector("#menu-select"),
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="attribute" type="string" required>
  The name of the attribute in the record.

  ```js JavaScript icon=code theme={"system"}
  menuSelect({
    // ...
    attribute: "brand",
  });
  ```
</ParamField>

<ParamField body="limit" type="number" default={10}>
  The maximum number of values to display.

  ```js JavaScript icon=code theme={"system"}
  menuSelect({
    // ...
    limit: 20,
  });
  ```
</ParamField>

<ParamField body="sortBy" type="string[] | function" default="Uses facetOrdering if set, ['name:asc']">
  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.

  <CodeGroup>
    ```js string[] theme={"system"}
    menuSelect({
      // ...
      sortBy: ["isRefined"],
    });
    ```

    ```js function theme={"system"}
    menuSelect({
      // ...
      sortBy(a, b) {
        return a.name < b.name ? 1 : -1;
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="templates" type="object">
  The [templates](#templates) to use for the widget.

  ```js JavaScript icon=code theme={"system"}
  menuSelect({
    // ...
    templates: {
      // ...
    },
  });
  ```
</ParamField>

<ParamField body="cssClasses" type="object" default="{}">
  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",
      ],
    },
  });
  ```
</ParamField>

<ParamField body="transformItems" type="function" default="items => items">
  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(),
      }));
    },
  });
  ```
</ParamField>

## 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).

<Note>
  The `html` function is available in InstantSearch.js version 4.46.0 or later.
</Note>

<ParamField body="item" type="string | function">
  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.

  <CodeGroup>
    ```js function theme={"system"}
    menuSelect({
      // ...
      templates: {
        item(item, { html }) {
          return html`<span
            >${item.label} - (${item.count.toLocaleString()})</span
          >`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    menuSelect({
      // ...
      templates: {
        item: "{{label}} ({{#helpers.formatNumber}}{{count}}{{/helpers.formatNumber}})",
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="defaultOption" type="string | function">
  The template to customize the first option of the select.

  <CodeGroup>
    ```js function theme={"system"}
    menuSelect({
      // ...
      templates: {
        defaultOption(data, { html }) {
          return html`<span>See all</span>`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    menuSelect({
      // ...
      templates: {
        defaultOption: "See all",
      },
    });
    ```
  </CodeGroup>
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<div class="ais-MenuSelect">
  <select class="ais-MenuSelect-select">
    <option class="ais-Menu-option">Apple (50)</option>
    <!-- more items -->
  </select>
</div>
```

## Customize the UI with `connectMenu`

If you want to create your own UI of the `menuSelect` widget, you can use connectors.

<Info>This connector is also used to build the [`menu`](/doc/api-reference/widgets/menu/js) widget.</Info>

To use `connectMenu`, you can import it with the declaration relevant to how you installed InstantSearch.js.

<CodeGroup>
  ```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()
  ```
</CodeGroup>

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
};
```

<Note>
  If SEO is important for your search page, ensure that your custom HTML is optimized for search engines:

  * Use `<a>` 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).
</Note>

#### Rendering options

<ParamField body="items" type="object[]">
  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 = `<select>
        ${items
          .map((item) => `<option value="${item.value}">${item.label}</option>`)
          .join("")}
      </select>
    `;
  };
  ```
</ParamField>

<ParamField body="canRefine" type="boolean">
  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 = `
      <select ${!canRefine ? "disabled" : ""}>
        ${items
          .map((item) => `<option value="${item.value}">${item.label}</option>`)
          .join("")}
      </select>
    `;
  };
  ```
</ParamField>

<ParamField body="refine" type="function">
  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 = `
      <option value="">See all</option>
      ${items
        .map(
          (item) =>
            `<option
              value="${item.value}"
              ${item.isRefined ? "selected" : ""}
            >
              ${item.label}
            </option>`,
        )
        .join("")}
    `;
  };
  ```
</ParamField>

<ParamField body="sendEvent" type="(eventType, facetValue) => void">
  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',
    }
  */
  ```
</ParamField>

<ParamField body="widgetParams" type="object">
  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"),
    }),
  ]);
  ```
</ParamField>

### 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

<ParamField body="attribute" type="string" required>
  The name of the attribute in the record.

  ```js JavaScript icon=code theme={"system"}
  customMenuSelect({
    attribute: "brand",
  });
  ```
</ParamField>

<ParamField body="limit" type="number" default={10}>
  The maximum number of values to display.

  ```js JavaScript icon=code theme={"system"}
  customMenuSelect({
    // ...
    limit: 20,
  });
  ```
</ParamField>

<ParamField body="sortBy" type="string[] | function" default="['isRefined', 'name:asc']">
  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).

  <CodeGroup>
    ```js string[] theme={"system"}
    customMenuSelect({
      // ...
      sortBy: ["name:asc"],
    });
    ```

    ```js function theme={"system"}
    customMenuSelect({
      // ...
      sortBy(a, b) {
        return a.name < b.name ? 1 : -1;
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="transformItems" type="function" default="items => items">
  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(),
      }));
    },
  });
  ```
</ParamField>

### Full example

<CodeGroup>
  ```html HTML theme={"system"}
  <div id="menu-select"></div>
  ```

  ```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 = `
      <option value="">See all</option>
      ${items
        .map(
          (item) =>
            `<option
              value="${item.value}"
              ${item.isRefined ? "selected" : ""}
            >
              ${item.label}
            </option>`,
        )
        .join("")}
    `;
  };

  // Create the custom widget
  const customMenuSelect = connectMenu(renderMenuSelect);

  // Instantiate the custom widget
  search.addWidgets([
    customMenuSelect({
      container: document.querySelector("#menu-select"),
      attribute: "brand",
    }),
  ]);
  ```
</CodeGroup>