API Reference / React InstantSearch Widgets / MenuSelect
Apr. 24, 2019

MenuSelect

Widget signature
<MenuSelect
  attribute={string}
  // Optional parameters
  defaultRefinement={string}
  limit={number}
  transformItems={function}
  translations={object}
/>

About this widget

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 added in attributes for faceting, either on the dashboard or using attributesForFaceting with the API.

Examples

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.

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

The value of the item selected by default.

1
2
3
4
<MenuSelect
  // ...
  defaultRefinement="Apple"
/>
limit
type: number
default: 10
Optional

The minimum number of diplayed items.

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.

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.
1
2
3
4
5
6
<MenuSelect
  // ...
  translations={{
    seeAllOption: 'See all',
  }}
/>

Customize the UI - 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 />

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.

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.

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.

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

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

The value of the item selected by default.

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

The minimum number of diplayed items.

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.

1
2
3
4
5
6
7
8
9
<CustomMenuSelect
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>

Full example

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

HTML output

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>

Did you find this page helpful?