🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
UI libraries / InstantSearch.js / Widgets

menuSelect

Signature 
menuSelect({
  container: string|HTMLElement,
  attribute: string,
  // Optional parameters
  limit: number,
  sortBy: string[]|function,
  templates: object,
  cssClasses: object,
  transformItems: function,
});
Import
Copy 
1

import { menuSelect } from 'instantsearch.js/es/widgets';
See code examples
See live example

About this widget

The menuSelect widget allows a user to select a single value to refine inside a select element.

Requirements

The attribute provided to the widget must be in attributes for faceting, either on the dashboard) or using attributesForFaceting with the API.

Examples

Copy 
1
2
3
4

menuSelect({
  container: '#menu-select',
  attribute: 'brand',
});

Options

Parameter Description
container
type: string|HTMLElement
Required

The CSS Selector or HTMLElement to insert the widget into.
Copy 
1
2
3
4

menuSelect({
  // ...
  container: '#menu-select',
});
attribute
type: string
Required

The name of the attribute in the record.
Copy 
1
2
3
4

menuSelect({
  // ...
  attribute: 'brand',
});
limit
type: number
default: 10
Optional

The maximum number of values to display.
Copy 
1
2
3
4

menuSelect({
  // ...
  limit: 20,
});
sortBy
type: string[]|function
default: Uses facetOrdering if set, ["name:asc"]
Optional

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.

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.
Copy 
1
2
3
4

menuSelect({
  // ...
  sortBy: ['isRefined'],
});
templates
type: object
Optional

The templates to use for the widget.
Copy 
1
2
3
4
5
6

menuSelect({
  // ...
  templates: {
    // ...
  },
});
cssClasses
type: object
default: {}
Optional

TThe CSS classes you can override:

  • 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.
Copy 
1
2
3
4
5
6
7
8
9
10

menuSelect({
  // ...
  cssClasses: {
    root: 'MyCustomMenuSelect',
    select: [
      'MyCustomMenuSelectElement',
      'MyCustomMenuSelectElement--subclass'
    ],
  },
});
transformItems
type: function
default: items => items
Optional

Receives the items, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them.
Copy 
1
2
3
4
5
6
7
8
9

menuSelect({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

Templates

You can customize parts of the widget’s UI using the Templates API.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.

The html function is available starting from v4.46.0.

Parameter Description
item
type: string|function
Optional

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.
Copy 
1
2
3
4
5
6
7
8

menuSelect({
  // ...
  templates: {
    item(item, { html }) {
      return html`<span>${item.label} - (${item.count.toLocaleString()})</span>`;
    },
  },
});
defaultOption
type: string|function
Optional

The template to customize the first option of the select.
Copy 
1
2
3
4
5
6
7
8

menuSelect({
  // ...
  templates: {
    defaultOption(data, { html }) {
      return html`<span>See all</span>`;
    },
  },
});

HTML output

Copy 
1
2
3
4
5
6
7
8

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

This connector is also used to build other widgets: Menu

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

Copy 
1

import { connectMenu } from 'instantsearch.js/es/connectors';

Then it’s a 3-step process:

// 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
  })
]);

See code examples

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

const renderMenuSelect = (renderOptions, isFirstRender) => {
  const {
    object[] items,
    boolean canRefine,
    function refine,
    function sendEvent,
    object widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
}

If SEO is critical to your search page, your custom HTML markup needs to be parsable:

  • use plain <a> tags with href attributes for search engines bots to follow them,
  • use semantic markup with structured data when relevant, and test it.

Refer to our SEO checklist for building SEO-ready search experiences.

Rendering options

Parameter Description
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.
Copy 
1
2
3
4
5
6
7
8
9
10
11

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>
  `;
};
canRefine
type: boolean

Returns true if a refinement can be applied.
Copy 
1
2
3
4
5
6
7
8
9
10
11

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>
  `;
};
refine
type: function

Sets the refinement and triggers a search.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

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('')}
  `;
};
sendEvent
type: (eventType, facetValue) => void

The function to send click events. The click event is automatically sent when refine is called. You can learn more about the insights middleware.

  • eventType: 'click'
  • facetValue: string
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

// 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',
  }
*/
widgetParams
type: object

All original widget options forwarded to the render function.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

const renderMenuSelect = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = '...';
};

// ...

search.addWidgets([
  customMenuSelect({
    container: document.querySelector('#menu-select'),
  })
]);

Create and instantiate the custom widget

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

  • Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
  • Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customMenuSelect = connectMenu(
  renderMenuSelect
);

search.addWidgets([
  customMenuSelect({
    attribute: string,
    // Optional parameters
    limit: number,
    sortBy: string[]|function,
    transformItems: function,
  })
]);

Instance options

Parameter Description
attribute
type: string
Required

The name of the attribute in the record.
Copy 
1
2
3

customMenuSelect({
  attribute: 'brand',
});
limit
type: number
default: 10
Optional

The maximum number of values to display.
Copy 
1
2
3
4

customMenuSelect({
  // ...
  limit: 20,
});
sortBy
type: string[]|function
default: ["isRefined", "name:asc"]
Optional

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.
Copy 
1
2
3
4

customMenuSelect({
  // ...
  sortBy: ['name:asc'],
});
transformItems
type: function
default: items => items
Optional

Receives the items, and is called before displaying them. Should return a new array with the same shape as the original array. Useful for mapping over the items to transform, and remove or reorder them.
Copy 
1
2
3
4
5
6
7
8
9

customMenuSelect({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

Full example

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

// 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',
  })
]);
Did you find this page helpful?
InstantSearch.js v4