API Reference / React InstantSearch / NumericMenu

NumericMenu

A
Signature 
<NumericMenu
  attribute={string}
  items={object[]}
  // Optional parameters
  defaultRefinement={string}
  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 NumericMenu widget displays a list of numeric filters in a list. Those numeric filters are pre-configured when creating the widget.

Requirements#

The values inside the attribute must be numbers, not strings.

Examples # A

Copy 
1
2
3
4
5
6
7
8
9
10
11

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

<NumericMenu
  attribute="price"
  items={[
    { label: '<= $10', end: 10 },
    { label: '$10 - $100', start: 10, end: 100 },
    { label: '$100 - $500', start: 100, end: 500 },
    { label: '>= $500', start: 500 },
  ]}
/>

Props # A

attribute #
type: string
Required

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

<NumericMenu
  // ...
  attribute="price"
/>
items #
type: object[]
Required

The list of ranges availables. Both start and end can be omitted inside the item. Only label is required.
Copy 
1
2
3
4
5
6
7
8
9

<NumericMenu
  // ...
  items={[
    { label: '<= $10', end: 10 },
    { label: '$10 - $100', start: 10, end: 100 },
    { label: '$100 - $500', start: 100, end: 500 },
    { label: '>= $500', start: 500 },
  ]}
/>
defaultRefinement #
type: string
Optional

The value of the item selected by default. This is a string with the shape "start:end", e.g., "5:10" or ":20".
Copy 
1
2
3
4

<NumericMenu
  // ...
  defaultRefinement="10:100"
/>
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

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

A mapping of keys to translation values.

  • all: the label of the largest range added automatically
Copy 
1
2
3
4
5
6

<NumericMenu
  // ...
  translations={{
    all: 'All',
  }}
/>

HTML output# A

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

<div class="ais-NumericMenu">
  <ul class="ais-NumericMenu-list">
    <li class="ais-NumericMenu-item ais-NumericMenu-item--selected">
      <label class="ais-NumericMenu-label">
        <input
          class="ais-NumericMenu-radio"
          type="radio"
          name="NumericMenu"
          checked
        />
        <span class="ais-NumericMenu-labelText">All</span>
      </label>
    </li>
    <li class="ais-NumericMenu-item">
      <label class="ais-NumericMenu-label">
        <input
          class="ais-NumericMenu-radio"
          type="radio"
          name="NumericMenu"
        />
        <span class="ais-NumericMenu-labelText">Less than 500</span>
      </label>
    </li>
  </ul>
</div>

Customize the UI with connectNumericMenu# A

If you want to create your own UI of the NumericMenu 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.

It’s a 3-step process:

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

// 2. Connect the component using the connector
const CustomNumericMenu = connectNumericMenu(NumericMenu);

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

See code examples

Create a React component#

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

Provided Props#

items #
type: object[]

The list of items the widget can display, with each item:

  • label: string: the label of the range.
  • value: string: the value of the range with the shape "start:end". When start is not applied, it’s ":end", same with "start:". When neither is applied, it’s an empty string.
  • isRefined: boolean: whether the value is currently refined.
  • noRefinement: boolean: whether the range contains results.
Copy 
1
2
3
4
5
6
7
8
9
10
11

const NumericMenu = ({ items }) => (
  <ul>
    {items.map(item => (
      <li key={item.value}>
        <a href="#" style={{ fontWeight: item.isRefined ? 'bold' : '' }}>
          {item.label}
        </a>
      </li>
    ))}
  </ul>
);
currentRefinement #
type: string

The currently applied refinement. It is a string with the shape "start:end". When start is not applied, it’s ":end", same with "start:". When neither is applied, it’s an empty string.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

const NumericMenu = ({ items, currentRefinement, refine }) => (
  <div>
    Current refinement: <code>{currentRefinement}</code>
    <ul>
      {items.map(item => (
        <li key={item.value}>
          <a
            href="#"
            style={{ fontWeight: item.isRefined ? 'bold' : '' }}
            onClick={event => {
              event.preventDefault();
              refine(item.value);
            }}
          >
            {item.label}
          </a>
        </li>
      ))}
    </ul>
  </div>
);
refine #
type: function

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

const NumericMenu = ({ items, refine }) => (
  <ul>
    {items.map(item => (
      <li key={item.value}>
        <a
          href="#"
          style={{ fontWeight: item.isRefined ? 'bold' : '' }}
          onClick={event => {
            event.preventDefault();
            refine(item.value);
          }}
        >
          {item.label}
        </a>
      </li>
    ))}
  </ul>
);
createURL #
type: function

Generates a URL for the corresponding search state.
Copy 
1
2
3
4
5
6
7
8
9

const NumericMenu = ({ items, createURL }) => (
  <ul>
    {items.map(item => (
      <li key={item.value}>
        <a href={createURL(item.value)}>{item.label}</a>
      </li>
    ))}
  </ul>
);

Create and instantiate your connected widget#

const CustomNumericMenu = connectNumericMenu(NumericMenu);

<CustomNumericMenu
  attribute={string}
  items={object[]}
  // optional parameters
  defaultRefinement={string}
  transformItems={function}
/>

Exposed Props#

Props #

attribute #
type: string
Required

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

<CustomNumericMenu
  // ...
  attribute="price"
/>
items #
type: object[]
Required

The list of available ranges. Both start and end can be omitted inside the item. Only label is required.
Copy 
1
2
3
4
5
6
7
8
9

<CustomNumericMenu
  // ...
  items={[
    { label: '<= $10', end: 10 },
    { label: '$10 - $100', start: 10, end: 100 },
    { label: '$100 - $500', start: 100, end: 500 },
    { label: '>= $500', start: 500 },
  ]}
/>
defaultRefinement #
type: string
Optional

The value of the item selected by default. This is a string with the shape "start:end", e.g., "5:10" or ":20".
Copy 
1
2
3
4

<CustomNumericMenu
  // ...
  defaultRefinement="10:100"
/>
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

<CustomNumericMenu
  // ...
  transformItems={items =>
    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

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

const NumericMenu = ({ items, refine, createURL }) => (
  <ul>
    {items.map(item => (
      <li key={item.value}>
        <a
          href={createURL(item.value)}
          style={{ fontWeight: item.isRefined ? 'bold' : '' }}
          onClick={event => {
            event.preventDefault();
            refine(item.value);
          }}
        >
          {item.label}
        </a>
      </li>
    ))}
  </ul>
);

const CustomNumericMenu = connectNumericMenu(NumericMenu);
Did you find this page helpful?
React InstantSearch v6