Algolia DevCon
Oct. 2–3 2024, virtual.
UI libraries / React InstantSearch / Widgets

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

Signature
const numericMenuApi = useNumericMenu({
  attribute: string,
  items: object[],
  // Optional parameters
  transformItems: function,
}
Import
1
import { useNumericMenu } from 'react-instantsearch';

About this Hook

React Hook for a list of numeric filters that are pre-configured when creating the widget.

Numeric menus let users choose a single value for a specific attribute.

Requirements

When using the useNumericMenu hook, check the following requirements:

  • The attribute provided to the hook is already declared as an attribute for faceting.
  • All values are numbers, not strings.

Examples

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
import React from 'react';
import { useNumericMenu } from 'react-instantsearch';

function NumericMenu(props) {
  const { items, refine } = useNumericMenu(props);

  return (
    <ul>
      {items.map((item) => (
        <li key={item.value}>
          <label>
            <input
              type="radio"
              name={item.attribute}
              defaultChecked={item.isRefined}
              onChange={(event) => {
                event.preventDefault();

                refine(item.value);
              }}
            />
            <span>{item.label}</span>
          </label>
        </li>
      ))}
    </ul>
  );
}

You can check the <NumericMenu> example for full markup.

Parameters

attribute
type: string
Required

The name of the attribute in the records.

1
2
3
4
const numericMenuApi = useNumericMenu({
  // ...
  attribute: 'categories',
});
items
type: object[]
Required

A list of all the options to display, with:

  • label: string: label of the option.
  • start: number: the option must be greater than or equal to start (lower bound).
  • end: number: the option must be smaller than or equal to end (upper bound).
1
2
3
4
5
6
7
8
9
const numericMenuApi = useNumericMenu({
  // ...
  items: [
    { label: 'All' },
    { label: 'Less than 500$', end: 500 },
    { label: 'Between 500$ - 1000$', start: 500, end: 1000 },
    { label: 'More than 1000$', start: 1000 },
  ],
});
transformItems
type: (items: object[], metadata: { results: SearchResults }) => object[]

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
const numericMenuApi = useNumericMenu({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },

  /* or, combined with results */
  transformItems(items, { results }) {
    return items.map(item => ({
      ...item,
      label: item.isRefined && results
        ? `${item.label} (${results.nbHits} hits)`
        : item.label,
    }));
  },
});

Returns

items
type: NumericMenuItem[]

The list of available options, with each option:

  • label: string: the label for the option.
  • value: string: the encoded URL of the bounds object with the {start, end} form. This value can be used verbatim in the web page and can be read by refine directly. If you want to inspect the value, you can do JSON.parse(window.decodeURI(value)) to get the object.
  • isRefined: boolean: whether the refinement is selected.
1
2
3
4
5
type NumericMenuItem = {
  value: string;
  label: string;
  isRefined: boolean;
};
canRefine
type: boolean

Whether the search can be refined.

createURL
type: (value: string) => string

Creates the next state URL of a selected refinement.

refine
type: (value: string) => string

Applies the selected refinement.

sendEvent
type: (eventType: string, facetValue: string, eventName?: string) => void

Sends an event to the Insights middleware.

Did you find this page helpful?