API Reference / React InstantSearch Hooks / useNumericMenu()
Signature
useNumericMenu({
  attribute: string,
  items: object[],
  // Optional parameters
  transformItems?: UseNumericMenuProps['transformItems'],
}: UseNumericMenuProps) => NumericMenuRenderState

About this Hook

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

NumericMenus lets the user 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
import React from 'react';
import { useNumericMenu } from 'react-instantsearch-hooks-web';

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

  return <>{/* Your JSX */}</>;
}

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: UseNumericMenuProps['transformItems']

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;
};
hasNoResults
type: boolean

Whether the search has results.

createURL
type: (value: string) => string

Creates the next state URL of a selected refinement.

refine
type: (value: string) => string

Applies the selected refinement.

hasNoResults
type: boolean

Whether the search has results.

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

Sends an event to the Insights middleware.

Did you find this page helpful?