menu

Filter results with a single-select menu

The menu widget displays a list of facet values where users can select only one value at a time. It’s ideal for mutually exclusive filters like product type or department.

Usage

const menu = instantsearch.widgets.menu({
  container: '#category-menu',
  attribute: 'category',
});

search.addWidget(menu);

Examples

Basic Menu

instantsearch.widgets.menu({
  container: '#category',
  attribute: 'category',
  limit: 10,
});

With Show More

instantsearch.widgets.menu({
  container: '#brands',
  attribute: 'brand',
  limit: 5,
  showMore: true,
  showMoreLimit: 20,
});

With Custom Sorting

instantsearch.widgets.menu({
  container: '#types',
  attribute: 'type',
  sortBy: ['count:desc', 'name:asc'],
});

Options

container · string | HTMLElement · required

CSS Selector or HTMLElement to insert the widget.

attribute · string · required

The name of the attribute in your records. Must be declared as an attribute for faceting.

limit · number · default: "10"

Maximum number of facet values to display.

showMore · boolean · default: "false"

Whether to display a “Show more” button.

showMoreLimit · number · default: "20"

Maximum number of facet values when “Show more” is clicked.

sortBy · string[] | function · default: "['name:asc']"

How to sort refinements. Available values:

• 'count:asc' / 'count:desc'
• 'name:asc' / 'name:desc'
• 'isRefined'

transformItems · function

Function to transform the items before rendering.

(items: object[]) => object[]

templates · object

Templates to customize the widget rendering.

Show properties

item · Template

Template for each item. Receives count, label, value, isRefined, url.

showMoreText · Template

Template for the “Show more” button. Receives isShowingMore.

cssClasses · object

CSS classes to add to the widget elements.

Show properties

root · string | string[]

CSS class for the root element.

noRefinementRoot · string | string[]

CSS class when no refinements are available.

list · string | string[]

CSS class for the list element.

item · string | string[]

CSS class for each item.

selectedItem · string | string[]

CSS class for the selected item.

link · string | string[]

CSS class for the link.

label · string | string[]

CSS class for the label.

count · string | string[]

CSS class for the count.

HTML Output

<div class="ais-Menu">
  <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">Electronics</span>
        <span class="ais-Menu-count">4,123</span>
      </a>
    </li>
    <li class="ais-Menu-item">
      <a class="ais-Menu-link" href="#">
        <span class="ais-Menu-label">Clothing</span>
        <span class="ais-Menu-count">2,984</span>
      </a>
    </li>
  </ul>
  <button class="ais-Menu-showMore">Show more</button>
</div>

Requirements

The attribute must be declared as an attribute for faceting in your Algolia index settings.