widgets menu

Description

Create a menu based on a facet. A menu displays facet values and let the user selects only one value at a time. It also displays an empty value which lets the user “unselect” any previous selection.

Requirements

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

Live example

You can find an example at the end of the page or a live example in our widget showcase.

Usage

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

const widget = instantsearch.widgets.menu({ 
  container: string|HTMLElement, 
  attribute: string, 
  sortBy: [Array<string>|function], 
  templates: [MenuTemplates], 
  limit: [number], 
  showMore: [boolean], 
  showMoreLimit: [number], 
  cssClasses: [MenuCSSClasses], 
  transformItems: [(Array<object>) => Array<object>], 
}: MenuWidgetOptions);

search.addWidget(widget);

Options

MenuWidgetOptions

• containerstring|HTMLElement

  CSS Selector or HTMLElement to insert the widget.

• attributestring

  Name of the attribute for faceting

• sortBy[Array<string>|function]
  Default value: ['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.

• templates[MenuTemplates]

  Customize the output through templating.

• limit[number]
  Default value: 10

  How many facets values to retrieve.

• showMore[boolean]
  Default value: false

  Limit the number of results and display a showMore button.

• showMoreLimit[number]
  Default value: 20

  Max number of values to display when showing more.

• cssClasses[MenuCSSClasses]

  CSS classes to add to the wrapping elements.

• transformItems[(Array<object>) => Array<object>]

  Function to transform the items passed to the templates.

MenuTemplates

• item[string|({count: number, cssClasses: object, isRefined: boolean, label: string, url: string, value: string}) => string]

  Item template. The string template gets the same values as the function.

• showMoreText[string]

  Template used for the show more text, provided with isShowingMore data property.

MenuCSSClasses

• root[string|Array<string>]

  CSS class to add to the root element.

• noRefinementRoot[string|Array<string>]

  CSS class to add to the root element when no refinements.

• list[string|Array<string>]

  CSS class to add to the list element.

• item[string|Array<string>]

  CSS class to add to each item element.

• selectedItem[string|Array<string>]

  CSS class to add to each selected item element.

• link[string|Array<string>]

  CSS class to add to each link (when using the default template).

• label[string|Array<string>]

  CSS class to add to each label (when using the default template).

• count[string|Array<string>]

  CSS class to add to each count element (when using the default template).

• showMore[string|Array<string>]

  CSS class to add to the show more button.

• disabledShowMore[string|Array<string>]

  CSS class to add to the disabled show more button.

Widget

• render[function]

  Called after each search response has been received

• getConfiguration[function]

  Let the widget update the configuration of the search with new parameters

• init[function]

  Called once before the first search

Example

search.addWidget(
  instantsearch.widgets.menu({
    container: '#categories',
    attribute: 'hierarchicalCategories.lvl0',
    limit: 10,
  })
);

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