menu

Signature

menu({
  container: string | HTMLElement,
  attribute: string,
  // Optional parameters
  limit?: number,
  showMore?: boolean,
  showMoreLimit?: number,
  sortBy?: string[] | function,
  templates?: object,
  cssClasses?: object,
  transformItems?: function,
});

Import

import { menu } from "instantsearch.js/es/widgets";

View demo

The menu widget displays a menu that lets users choose a single value for a specific attribute.

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

The attribute provided to the widget must be in attributes for faceting, either on the dashboard or using the attributesForFaceting parameter with the API.

Examples

JavaScript

menu({
  container: "#menu",
  attribute: "categories",
});

Options

container

string | HTMLElement

required

The CSS Selector of the DOM element inside which the widget is inserted.

menu({
  // ...
  container: "#menu",
});

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. When you enable the showMore feature, this is the number of facet values to display before clicking the “Show more” button.

JavaScript

menu({
  // ...
  limit: 20,
});

showMoreLimit

number

How many facet values to retrieve when showing more.

JavaScript

menu({
  // ...
  showMoreLimit: 30,
});

sortBy

string[] | function

How to sort refinements. Must be one 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"

Default: ["isRefined", "name:asc]It’s also possible to give a function, which receives items two by two, like JavaScript’s Array.sort.If facetOrdering is set for this facet in renderingContent, and no value for sortBy is passed to this widget, facetOrdering is used, and the default order as a fallback.

menu({
  // ...
  sortBy: ["count:desc", "name:asc"],
});

templates

object

The templates to use for the widget.

JavaScript

menu({
  // ...
  templates: {
    // ...
  },
});

cssClasses

object

default:"{}"

The CSS classes you can override:

root. The root element of the widget.
noRefinementRoot. The root element if there are no refinements.
list. The list of results.
item. The list items. They contain the link and separator.
selectedItem. The selected item in the list. This is the last one, or the root one if there are no refinements.
link. The link element of each item.
label. The label element of each item.
count. The count element of each item.
showMore. The “Show more” button.
disabledShowMore. The “Show more” button when disabled.

JavaScript

menu({
  // ...
  cssClasses: {
    root: "MyCustomMenu",
    list: ["MyCustomMenuList", "MyCustomMenuList--sub-class"],
  },
});

transformItems

function

default:"items => items"

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

menu({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

// or: combined with results
menu({
  // ...
  transformItems(items, { results }) {
    return items.map((item) => ({
      ...item,
      label: item.isRefined
        ? `${item.label} (${results.nbPages} pages)`
        : item.label,
    }));
  },
});

Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

item

string | function

Item template. It exposes:

count. The number of occurrences of the facet in the result set.
isRefined. Returns true if the value is selected.
label. The label to display.
value. The value used for refining.
url. The URL with the selected refinement.
cssClasses. An object containing all the computed classes for the item.

menu({
  // ...
  templates: {
    item(data, { html }) {
      const { label, count, url, cssClasses } = data;

      return html`
        <a class="${cssClasses.link}" href="${url}">
          <span class="${cssClasses.label}">${label}</span>
          <span class="${cssClasses.count}"> ${count.toLocaleString()} </span>
        </a>
      `;
    },
  },
});

showMoreText

string | function

The template for the “Show more” button text. It exposes:

isShowingMore: boolean. Whether the list is expanded.

menu({
  // ...
  templates: {
    showMoreText(data, { html }) {
      return html`<span
        >${data.isShowingMore ? "Show less" : "Show more"}</span
      >`;
    },
  },
});

HTML output

HTML

<div class="ais-Menu">
  <div class="ais-Menu-searchBox">
    <!-- SearchBox widget here -->
  </div>
  <ul class="ais-Menu-list">
    <li class="ais-Menu-item ais-Menu-item--selected">
      <a class="ais-Menu-link" href="#">
        <span class="ais-Menu-label">Appliances</span>
        <span class="ais-Menu-count">4,306</span>
      </a>
    </li>
    <li class="ais-Menu-item">
      <a class="ais-Menu-link" href="#">
        <span class="ais-Menu-label">Audio</span>
        <span class="ais-Menu-count">1,570</span>
      </a>
    </li>
  </ul>
  <button class="ais-Menu-showMore">Show more</button>
</div>

Customize the UI with `connectMenu`

If you want to create your own UI of the menu widget, you can use connectors.

This connector is also used to build the menuSelect widget.

To use connectMenu, you can import it with the declaration relevant to how you installed InstantSearch.js.

import { connectMenu } from 'instantsearch.js/es/connectors';

Then it’s a 3-step process:

JavaScript

// 1. Create a render function
const renderMenu = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customMenu = connectMenu(renderMenu);

// 3. Instantiate
search.addWidgets([
  customMenu({
    // Widget parameters
  }),
]);

Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

JavaScript

const renderMenu = (renderOptions, isFirstRender) => {
  const {
    items,
    canRefine,
    refine,
    sendEvent,
    createURL,
    isShowingMore,
    canToggleShowMore,
    toggleShowMore,
    widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
};

If SEO is important for your search page, ensure that your custom HTML is optimized for search engines:

Use <a> tags with href attributes to allow search engine bots to follow links.
Use semantic HTML and include structured data when relevant.

For more guidance, see the SEO checklist.

Render options

items

object[]

The elements that can be refined for the current search results. With each item:

value: string. The value of the menu item.
label: string. The label of the menu item.
count: number. The number of results matched after a refinement is applied.
isRefined: boolean. Indicates if the refinement is applied.

JavaScript

const renderMenu = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

  document.querySelector("#menu").innerHTML = `
    <ul>
      ${items
        .map(
          (item) => `
            <li>
              <a href="#">
                ${item.label} (${item.count})
              </a>
            </li>
          `,
        )
        .join("")}
    </ul>
  `;
};

canRefine

boolean

required

Indicates if search state can be refined.

JavaScript

const renderMenu = (renderOptions, isFirstRender) => {
  const { items, canRefine, refine } = renderOptions;

  const container = document.querySelector("#menu");
  if (!canRefine) {
    container.innerHTML = "";
    return;
  }
};

refine

function

A function to toggle a refinement.

JavaScript

const renderMenu = (renderOptions, isFirstRender) => {
  const { items, refine } = renderOptions;

  const container = document.querySelector("#menu");

  container.innerHTML = `
    <ul>
      ${items
        .map(
          (item) => `
            <li>
              <a
                href="#"
                data-value="${item.value}"
                style="font-weight: ${item.isRefined ? "bold" : ""}"
              >
                ${item.label} (${item.count})
              </a>
            </li>
          `,
        )
        .join("")}
    </ul>
  `;

  [...container.querySelectorAll("a")].forEach((element) => {
    element.addEventListener("click", (event) => {
      event.preventDefault();
      refine(event.currentTarget.dataset.value);
    });
  });
};

sendEvent

(eventType, facetValue) => void

The function to send click events.

The view event is automatically sent when the facets are rendered.
The click event is automatically sent when refine is called.
You can learn more about the middleware.
eventType: 'click'
facetValue: string

JavaScript

// For example,
sendEvent("click", "Apple");

/*
  A payload like the following will be sent to the `insights` middleware.
  {
    eventType: 'click',
    insightsMethod: 'clickedFilters',
    payload: {
      eventName: 'Filter Applied',
      filters: ['brand:"Apple"'],
      index: '',
    },
    widgetType: 'ais.menu',
  }
*/

createURL

function

default: (item.value) => string

Generates a URL for the corresponding search state.

JavaScript

const renderMenu = (renderOptions, isFirstRender) => {
  const { items, createURL } = renderOptions;

  document.querySelector("#menu").innerHTML = `
    <ul>
      ${items
        .map(
          (item) => `
            <li>
              <a
                href="${createURL(item.value)}"
                style="font-weight: ${item.isRefined ? "bold" : ""}"
              >
                ${item.label} (${item.count})
              </a>
            </li>
          `,
        )
        .join("")}
    </ul>
  `;
};

isShowingMore

boolean

Returns true if the menu is displaying all the menu items.

JavaScript

const renderMenu = (renderOptions, isFirstRender) => {
  const { items, isShowingMore, toggleShowMore } = renderOptions;

  const container = document.querySelector("#menu");

  if (isFirstRender) {
    const ul = document.createElement("ul");
    const button = document.createElement("button");
    button.textContent = "Show more";

    button.addEventListener("click", () => {
      toggleShowMore();
    });

    container.appendChild(ul);
    container.appendChild(button);
  }

  container.querySelector("ul").innerHTML = items
    .map(
      (item) => `
        <li>
          <a href="#">
            ${item.label} (${item.count})
          </a>
        </li>
      `,
    )
    .join("");

  container.querySelector("button").textContent = isShowingMore
    ? "Show less"
    : "Show more";
};

canToggleShowMore

boolean

Returns true if the “Show more” button can be activated (enough items to display more and not already displaying more than limit items).

JavaScript

const renderMenu = (renderOptions, isFirstRender) => {
  const { items, canToggleShowMore, toggleShowMore } = renderOptions;

  const container = document.querySelector("#menu");

  if (isFirstRender) {
    const ul = document.createElement("ul");
    const button = document.createElement("button");
    button.textContent = "Show more";

    button.addEventListener("click", () => {
      toggleShowMore();
    });

    container.appendChild(ul);
    container.appendChild(button);
  }

  container.querySelector("ul").innerHTML = items
    .map(
      (item) => `
        <li>
          <a href="#">
            ${item.label} (${item.count})
          </a>
        </li>
      `,
    )
    .join("");

  container.querySelector("button").disabled = !canToggleShowMore;
};

toggleShowMore

function

Toggles the number of displayed values between limit and showMoreLimit.

JavaScript

const renderMenu = (renderOptions, isFirstRender) => {
  const { items, toggleShowMore } = renderOptions;

  const container = document.querySelector("#menu");

  if (isFirstRender) {
    const ul = document.createElement("ul");
    const button = document.createElement("button");
    button.textContent = "Show more";

    button.addEventListener("click", () => {
      toggleShowMore();
    });

    container.appendChild(ul);
    container.appendChild(button);
  }

  container.querySelector("ul").innerHTML = items
    .map(
      (item) => `
        <li>
          <a href="#">
            ${item.label} (${item.count})
          </a>
        </li>
      `,
    )
    .join("");
};

All original widget options forwarded to the render function.

JavaScript

const renderMenu = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = "...";
};

// ...

search.addWidgets([
  customMenu({
    // ...
    container: document.querySelector("#menu"),
  }),
]);

First, create your custom widgets using a rendering function. Then, instantiate them with parameters. There are two kinds of parameters you can pass:

Instance parameters. Predefined options that configure Algolia’s behavior.
Custom parameters. Parameters you define to make the widget reusable and adaptable.

Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.

JavaScript

const customMenu = connectMenu(renderMenu);

search.addWidgets([
  customMenu({
    attribute,
    // Optional instance params
    limit,
    showMoreLimit,
    sortBy,
    transformItems,
  }),
]);

Instance options

attribute

string

required

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

JavaScript

customMenu({
  attribute: "categories",
});

limit

number

default:10

How many facet values to retrieve. When you enable the showMore feature, this is the number of facet values to display before clicking the “Show more” button.

JavaScript

customMenu({
  // ...
  limit: 20,
});

showMoreLimit

number

default:10

How many facet values to retrieve when showing more.

JavaScript

customMenu({
  // ...
  showMoreLimit: 20,
});

sortBy

string[] | function

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

"count:asc"
"count:desc"
"name:asc"
"name:desc"
"isRefined"

Default: ["isRefined", "name:asc"]It’s also possible to give a function, which receives items two by two, like JavaScript’s Array.sort.If facetOrdering is set for this facet in renderingContent, and no value for sortBy is passed to this widget, facetOrdering is used, and the default order as a fallback.

customMenu({
  // ...
  sortBy: ["count:desc", "name:asc"],
});

transformItems

function

JavaScript

customMenu({
  // ...
  transformItems(items) {
    return items.map((item) => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

// or, combined with results
customMenu({
  // ...
  transformItems(items, { results }) {
    return items.map((item) => ({
      ...item,
      label: item.isRefined
        ? `${item.label} (${results.nbPages} pages)`
        : item.label,
    }));
  },
});

Full example

<div id="menu"></div>

InstantSearch.js

Import

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectMenu`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example

InstantSearch.js

​Import

​About this widget

​Requirements

​Examples

​Options

​Templates

​HTML output

​Customize the UI with connectMenu

​Create a render function

​Render options

​Create and instantiate the custom widget

​Instance options

​Full example

Import

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectMenu`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example