API Reference / React InstantSearch / MenuSelect

MenuSelect

A
Signature 
<MenuSelect
  attribute={string}
  // Optional parameters
  defaultRefinement={string}
  facetOrdering={boolean}
  limit={number}
  transformItems={function}
  translations={object}
/>
See code examples
See live example

About this widget # A

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

Copy 
1
2
3

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

<MenuSelect attribute="brand" />

Props # A

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

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

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