Menu

Shows a menu for refining search results based on a selected facet value.

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

<Menu
  attribute={string}
  // Optional parameters
  limit={number}
  showMore={boolean}
  showMoreLimit={number}
  sortBy={string[] | function}
  transformItems={function}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { Menu } from "react-instantsearch";

View demo

About this widget

<Menu> is a widget that displays a list of facets and lets users choose a single value.

The <Menu> widget uses a hierarchical refinement internally, so it can’t refine values that include the default separator (>). To support these values, use the <HierarchicalMenu> widget instead.

Requirements

Ensure that the attribute provided to the hook is already declared as an attribute for faceting.

You can also create your own UI with useMenu.

Examples

JavaScript

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, Menu } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <Menu attribute="categories" />
    </InstantSearch>
  );
}

Props

attribute · string · required

The name of the attribute in the records.

To avoid unexpected behavior, you can’t use the same attribute prop in a different type of widget.

JavaScript

<Menu attribute="categories" />;

limit · number · default: 10

How many facet values to retrieve.

showMore and showMoreLimit determine the number of facet values to display before clicking the Show more button.

JavaScript

<Menu
  // ...
  limit={15}
/>;

showMore · boolean · default: false

Whether to display a button that expands the number of items.

JavaScript

<Menu
  // ...
  showMore={true}
/>;

showMoreLimit · number

The maximum number of items to display if the widget is showing more than the limit items.

JavaScript

<Menu
  // ...
  showMoreLimit={25}
/>;

sortBy · string[] | (a: FacetValue, b: FacetValue) => number

How to sort refinements. Must be one or more of the following strings:

• "count" (same as "count:desc")
• "count:asc"
• "count:desc"
• "name" (same as "name:asc")
• "name:asc"
• "name:desc"
• "isRefined" (same as "isRefined:asc")
• "isRefined:asc"
• "isRefined:desc"

You can also use a sort function that behaves like the standard JavaScript compareFunction.

If you leave the default setting for this parameter, and you’ve set facetOrdering for this facet in renderingContent, facets are sorted using facetOrdering and use the default order as a fallback.

String

<Menu
  // ...
  sortBy={["count:desc", "name:asc"]}
/>;

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 transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.label.toUpperCase(),
  }));
};

function Search() {
  return (
    <Menu
      // ...
      transformItems={transformItems}
    />
  );
}

classNames · Partial<MenuClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

• root. The root element of the widget.
• noRefinementRoot. The root element when there are no refinements.
• list. The list element.
• item. Each item element..
• selectedItem. The selected item element.
• link. The link of each item.
• label. The label of each item.
• count. The count of each item.
• showMore. The “Show more” button.
• disabledShowMore. The disabled “Show more” button.

JavaScript

<Menu
  // ...
  classNames={{
    root: "MyCustomMenu",
    list: "MyCustomMenuList MyCustomMenuList--subclass",
  }}
/>;

translations · Partial<MenuTranslations>

A mapping of keys to translation values.

• showMoreButtonText. The text for the “Show more” button.

JavaScript

<Menu
  // ...
  showMore
  translations={{
    showMoreButtonText({ isShowingMore }) {
      return isShowingMore ? "Show less brands" : "Show more brands";
    },
  }}
/>;

...props · React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.

JavaScript

<Menu
  // ...
  className="MyCustomMenu"
  title="My custom title"
/>;

Hook

React InstantSearch let you create your own UI for the <Menu> widget with useMenu. Hooks provide APIs to access the widget state and interact with InstantSearch.

The useMenu Hook accepts parameters and returns APIs. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useMenu } from "react-instantsearch";

function CustomMenu(props) {
  const {
    items,
    createURL,
    refine,
    canRefine,
    isShowingMore,
    toggleShowMore,
    canToggleShowMore,
    sendEvent,
  } = useMenu(props);

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

Then, render the widget:

JavaScript

<CustomMenu {...props} />

Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

attribute · string · required

The name of the attribute in the records.

To avoid unexpected behavior, you can’t use the same attribute prop in a different type of widget.

JavaScript

const menuApi = useMenu({
  attribute: "categories",
});

limit · number · default: 10

How many facet values to retrieve.

showMore and showMoreLimit determine the number of facet values to display before clicking the Show more button.

JavaScript

const menuApi = useMenu({
  // ...
  limit: 5,
});

showMore · boolean · default: false

Whether to display a button that expands the number of items.

JavaScript

const menuApi = useMenu({
  // ...
  showMore: true,
});

showMoreLimit · number

The maximum number of items to display if the widget is showing more than the limit items.

JavaScript

const menuApi = useMenu({
  // ...
  showMoreLimit: 20,
});

sortBy · string[] | (a: FacetValue, b: FacetValue) => number

How to sort refinements. Must be one or more of the following strings:

• "count" (same as "count:desc")
• "count:asc"
• "count:desc"
• "name" (same as "name:asc")
• "name:asc"
• "name:desc"
• "isRefined" (same as "isRefined:asc")
• "isRefined:asc"
• "isRefined:desc"

You can also use a sort function that behaves like the standard JavaScript compareFunction.

If you leave the default setting for this parameter, and you’ve set facetOrdering for this facet in renderingContent, facets are sorted using facetOrdering and use the default order as a fallback.

String

const menuApi = useMenu({
  // ...
  sortBy: ["count:desc", "name:asc"],
});

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 transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.label.toUpperCase(),
  }));
};

function Menu() {
  const menuApi = useMenu({
    // ...
    transformItems,
  });

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

APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

items · MenuItem[]

The elements that can be refined for the current search results.

type MenuItem = {
  /**
   * The value of the menu item.
   */
  value: string;
  /**
   * Human-readable value of the menu item.
   */
  label: string;
  /**
   * Number of matched results after refinement is applied.
   */
  count: number;
  /**
   * Indicates if the menu item is refined.
   */
  isRefined: boolean;
};

createURL · (value: string) => string

Creates the next state URL of a selected refinement.

refine · (value: string) => string

Applies the selected refinement.

canRefine · boolean

Whether a refinement can be applied.

isShowingMore · boolean

Whether the menu is displaying all the menu items.

toggleShowMore · () => void

Toggles the number of values displayed between limit and showMoreLimit.

canToggleShowMore · boolean

Whether the Show more button can be activated, meaning there are enough additional items to display, or already displaying over the limit items.

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

Sends an event to the Insights middleware.

Example

JavaScript

import React from "react";
import { useMenu } from "react-instantsearch";

function CustomMenu(props) {
  const {
    items,
    refine,
    createURL,
    canToggleShowMore,
    toggleShowMore,
    isShowingMore,
  } = useMenu(props);

  return (
    <>
      <ul>
        {items.map((item) => (
          <li key={item.label}>
            <a
              href={createURL(item.value)}
              onClick={(event) => {
                event.preventDefault();

                refine(item.value);
              }}
              style={{ fontWeight: item.isRefined ? "bold" : "normal" }}
            >
              <span>{item.label}</span>
              <span>{item.count}</span>
            </a>
          </li>
        ))}
      </ul>
      {props.showMore && (
        <button disabled={!canToggleShowMore} onClick={toggleShowMore}>
          {isShowingMore ? "Show less" : "Show more"}
        </button>
      )}
    </>
  );
}