Skip to main content
This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.
Signature
  const numericMenuApi = useNumericMenu({
    attribute: string,
    items: object[],
    // Optional parameters
    transformItems: function,
  }

Import

JavaScript
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

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

Examples

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
string
required
The name of the attribute in the records.
JavaScript
const numericMenuApi = useNumericMenu({
  // ...
  attribute: "categories",
});
items
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).
JavaScript
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
(items: object[], metadata: { results: SearchResults }) => object[]
A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.
JavaScript
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
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.
TypeScript
type NumericMenuItem = {
  value: string;
  label: string;
  isRefined: boolean;
};
canRefine
boolean
Whether the search can be refined.
createURL
(value: string) => string
Creates the next state URL of a selected refinement.
refine
(value: string) => string
Applies the selected refinement.
sendEvent
(eventType: string, facetValue: string, eventName?: string) => void
Sends an event to the Insights middleware.
I