UI libraries / React InstantSearch / Widgets

Dec. 04, 2023

useNumericMenu()

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

Copy

1
import { useNumericMenu } from 'react-instantsearch';

See code examples

See live example

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

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

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
29
30
31
import React from 'react';
import {
  useNumericMenu,
  UseNumericMenuProps,
} from 'react-instantsearch';

function NumericMenu(props: UseNumericMenuProps) {
  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

Parameter Description


            attribute

type: string

Required

The name of the attribute in the records.

Copy
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).

Copy
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).

Copy
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

Parameter Description


            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.

Copy
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.