API Reference / React InstantSearch / MenuSelect

MenuSelect

Signature 
<MenuSelect
  attribute={string}
  // Optional parameters
  defaultRefinement={string}
  facetOrdering={boolean}
  limit={number}
  transformItems={function}
  translations={object}
/>
Import
Copy 
1

import { MenuSelect } from 'react-instantsearch-dom';
See code examples
See live example

About this widget

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

The MenuSelect widget displays a select element that lets the user choose a single value for a specific attribute.

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

import { MenuSelect } from 'react-instantsearch-dom';

<MenuSelect attribute="brand" />

Props

attribute
type: string
Required

The name of the attribute in the record.
Copy 
1

<MenuSelect attribute="brand" />
defaultRefinement
type: string
Optional

The value of the item selected by default.
Copy 
1
2
3
4

<MenuSelect
  // ...
  defaultRefinement="Apple"
/>
facetOrdering
type: boolean
default: true
Optional

Apply the rules of renderingContent.facetOrdering for this widget.
Copy 
1
2
3
4

<MenuSelect
  // ...
  facetOrdering
/>
limit
type: number
default: 10
Optional

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

<MenuSelect
  // ...
  limit={20}
/>
transformItems
type: function
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.
Copy 
1
2
3
4
5
6
7
8
9

<MenuSelect
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>
translations
type: object
Optional

A mapping of keys to translation values.

  • seeAllOption: the label of the option to select all values.
Copy 
1
2
3
4
5
6

<MenuSelect
  // ...
  translations={{
    seeAllOption: 'See all',
  }}
/>

HTML output

Copy 
1
2
3
4
5
6

<div class="ais-MenuSelect">
  <select class="ais-MenuSelect-select">
    <option class="ais-MenuSelect-option" value="Most relevant">Appliances (4306)</option>
    <option class="ais-MenuSelect-option" value="Lowest price">Audio (1570)</option>
  </select>
</div>

Customize the UI with connectMenu

If you want to create your own UI of the MenuSelect widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

This connector is also used to build other widgets: Menu

It’s a 3-step process:

// 1. Create a React component
const MenuSelect = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomMenuSelect = connectMenu(MenuSelect);

// 3. Use your connected widget
<CustomMenuSelect />

See code examples

Create a React component

const MenuSelect = ({
  object[] items,
  string currentRefinement,
  function refine,
}) => {
  // return the DOM output
};

Provided Props

items
type: object[]

The list of items the widget can display.
Copy 
1
2
3
4
5
6
7
8
9
10

const MenuSelect = ({ items }) => (
  <select>
    <option value="">See all options</option>
    {items.map(item => (
      <option key={item.label} value={item.value}>
        {item.label}
      </option>
    ))}
  </select>
);
currentRefinement
type: string

The currently applied refinement.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

const MenuSelect = ({ items, currentRefinement, refine }) => (
  <div>
    <p>Current refinement: {currentRefinement}</p>
    <select
      value={currentRefinement || ''}
      onChange={event => refine(event.currentTarget.value)}
    >
      <option value="">See all options</option>
      {items.map(item => (
        <option
          key={item.label}
          value={item.isRefined ? currentRefinement : item.value}
        >
          {item.label}
        </option>
      ))}
    </select>
  </div>
);
refine
type: function

Selects a refinement.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

const MenuSelect = ({ items, currentRefinement, refine }) => (
  <select
    value={currentRefinement || ''}
    onChange={event => refine(event.currentTarget.value)}
  >
    <option value="">See all options</option>
    {items.map(item => (
      <option
        key={item.label}
        value={item.isRefined ? currentRefinement : item.value}
      >
        {item.label}
      </option>
    ))}
  </select>
);

Create and instantiate your connected widget

const CustomMenuSelect = connectMenu(MenuSelect);

<CustomMenuSelect
  attribute={string}
  // optional parameters
  defaultRefinement={string}
  limit={number}
  transformItems={function}
/>

Exposed Props

attribute
type: string
Required

The name of the attribute in the record
Copy 
1

<CustomMenuSelect attribute="brand" />
defaultRefinement
type: string
Optional

The value of the item selected by default.
Copy 
1
2
3
4

<CustomMenuSelect
  // ...
  defaultRefinement="Apple"
/>
limit
type: number
default: 10
Optional

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

<CustomMenuSelect
  // ...
  limit={20}
/>
transformItems
type: function
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.
Copy 
1
2
3
4
5
6
7
8
9

<CustomMenuSelect
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>

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.

Full example

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

import { connectMenu } from 'react-instantsearch-dom';

const MenuSelect = ({ items, currentRefinement, refine }) => (
  <select
    value={currentRefinement || ''}
    onChange={event => refine(event.currentTarget.value)}
  >
    <option value="">See all options</option>
    {items.map(item => (
      <option
        key={item.label}
        value={item.isRefined ? currentRefinement : item.value}
      >
        {item.label}
      </option>
    ))}
  </select>
);

const CustomMenuSelect = connectMenu(MenuSelect);
Did you find this page helpful?
React InstantSearch v6