connectors connectMenu

Edit this page

Description

Menu connector provides the logic to build a widget that will give the user the ability to choose a single value for a specific facet. The typical usage of menu is for navigation in categories.

This connector provides a toggleShowMore() function to display more or less items and a refine() function to select an item. While selecting a new element, the refine will also unselect the one that is currently selected.

Requirement: the attribute passed as attributeName must be present in “attributes for faceting” on the Algolia dashboard or configured as attributesForFaceting via a set settings call to the Algolia API.

Usage

Usage
const search= instantsearch(/* parameters */);

const makeMenu= instantsearch.connectors.connectMenu(
function renderFn(
renderOpts: MenuRenderingOptions,
isFirstRendering: boolean) {
// render the custom Menu widget
} );

const customMenu = makeMenu(instanceOpts: CustomMenuWidgetOptions);
search.addWidget(customMenu);

Connector options

MenuRenderingOptions

  • itemsArray<MenuItem>

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

  • createURL(item.value) => string

    Creates the URL for a single item name in the list.

  • refine(item.value) => undefined

    Filter the search to item value.

  • canRefineboolean

    True if refinement can be applied.

  • widgetParamsObject

    All original CustomMenuWidgetOptions forwarded to the renderFn.

  • isShowingMoreboolean

    True if the menu is displaying all the menu items.

  • toggleShowMorefunction

    Toggles the number of values displayed between limit and showMore.limit.

  • canToggleShowMoreboolean

    true if the toggleShowMore button can be activated (enough items to display more or already displaying more than limit items)

MenuItem

  • valuestring

    The value of the menu item.

  • labelstring

    Human-readable value of the menu item.

  • countnumber

    Number of results matched after refinement is applied.

  • booleanisRefined

    Indicates if the refinement is applied.

CustomMenuWidgetOptions

  • attributeNamestring

    Name of the attribute for faceting (eg. “free_shipping”).

  • limit[number]
    Default value: 10

    How many facets values to retrieve.

  • showMoreLimit[number]
    Default value: undefined

    How many facets values to retrieve when toggleShowMore is called, this value is meant to be greater than limit option.

  • sortBy[Array<string>|function]
    Default value: ['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[(Array<object>) => Array<object>]

    Function to transform the items passed to the templates.

Example

// custom `renderFn` to render the custom Menu widget
function renderFn(MenuRenderingOptions, isFirstRendering) {
  if (isFirstRendering) {
    MenuRenderingOptions.widgetParams.containerNode
      .html('<select></select');

    MenuRenderingOptions.widgetParams.containerNode
      .find('select')
      .on('change', function(event) {
        MenuRenderingOptions.refine(event.target.value);
      });
  }

  var options = MenuRenderingOptions.items.map(function(item) {
    return item.isRefined
      ? '<option value="' + item.value + '" selected>' + item.label + '</option>'
      : '<option value="' + item.value + '">' + item.label + '</option>';
  });

  MenuRenderingOptions.widgetParams.containerNode
    .find('select')
    .html(options);
}

// connect `renderFn` to Menu logic
var customMenu = instantsearch.connectors.connectMenu(renderFn);

// mount widget on the page
search.addWidget(
  customMenu({
    containerNode: $('#custom-menu-container'),
    attributeName: 'categories',
    limit: 10,
  })
);


Can't find what you are looking for? Open an issue, we'll get back to you.