Skip to main content
The Menu connector provides the logic to build a custom widget that lets users choose a single value for a specific facet. This is typically used for navigation in categories.
The attribute passed as attribute must be present in attributesForFaceting on the Algolia dashboard or configured via the API.

​
Usage

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

const customMenu = connectMenu(
  (renderOptions, isFirstRender) => {
    const { items, refine, widgetParams } = renderOptions;
    const { container } = widgetParams;
    
    container.innerHTML = `
      <ul>
        ${items.map(item => `
          <li>
            <a 
              href="#" 
              data-value="${item.value}"
              style="${item.isRefined ? 'font-weight: bold' : ''}"
            >
              ${item.label} (${item.count})
            </a>
          </li>
        `).join('')}
      </ul>
    `;
    
    container.querySelectorAll('a').forEach(link => {
      link.addEventListener('click', (e) => {
        e.preventDefault();
        refine(e.target.dataset.value);
      });
    });
  }
);

search.addWidgets([
  customMenu({
    container: document.querySelector('#menu'),
    attribute: 'category',
  }),
]);

​
Connector Options

​
attribute
string
required
Name of the attribute for faceting (e.g., “category”).
​
limit
number
default:"10"
How many facet values to retrieve.
​
showMore
boolean
default:"false"
Whether to display a button that expands the number of items.
​
showMoreLimit
number
default:"20"
How many facet values to retrieve when toggleShowMore is called.
​
sortBy
string[] | function
default:"['isRefined', 'name:asc']"
How to sort refinements. Possible values: count, isRefined, name:asc, name:desc.You can also use a sort function that behaves like the standard JavaScript compareFunction.
​
transformItems
(items: object[]) => object[]
Function to transform the items passed to the templates.

​
Render Options

​
items
Array<MenuItem>
The elements that can be refined for the current search results.Each item has:
  • value: The value of the menu item
  • label: Human-readable value of the item
  • count: Number of results matched after refinement
  • isRefined: Indicates if the refinement is applied
​
refine
(value: string) => void
Filters the search to the item value. Selecting a new item will unselect the current one.
​
createURL
(value: string) => string
Creates the URL for a single item name in the list.
​
canRefine
boolean
true if refinement can be applied.
​
isShowingMore
boolean
true if the menu is displaying all items.
​
toggleShowMore
() => void
Toggles the number of values displayed between limit and showMoreLimit.
​
canToggleShowMore
boolean
true if the toggleShowMore button can be activated.
​
sendEvent
function
Sends an event to the Insights middleware.
​
widgetParams
object
The options passed to the connector.

Build docs developers (and LLMs) love

Get started for freeTalk to us