widgets hierarchicalMenu

Description

The hierarchical menu widget is used to create a navigation based on a hierarchy of facet attributes.

It is commonly used for categories with subcategories.

All attributes (lvl0, lvl1 here) must be declared as attributes for faceting in your Algolia settings.

By default, the separator we expect is > (with spaces) but you can use a different one by using the separator option.

Requirements

Your objects must be formatted in a specific way to be able to display hierarchical menus. Here’s an example:

{
  "objectID": "123",
  "name": "orange",
  "categories": {
    "lvl0": "fruits",
    "lvl1": "fruits > citrus"
  }
}

Every level must be specified entirely. It’s also possible to have multiple values per level, for example:

{
  "objectID": "123",
  "name": "orange",
  "categories": {
    "lvl0": ["fruits", "vitamins"],
    "lvl1": ["fruits > citrus", "vitamins > C"]
  }
}

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.hierarchicalMenu({ 
  container: string|HTMLElement, 
  attributes: Array<string>, 
  separator: [string], 
  rootPath: [string], 
  showParentLevel: [boolean], 
  limit: [number], 
  showMore: [boolean], 
  showMoreLimit: [number], 
  sortBy: [Array<string>|function], 
  transformItems: [(Array<object>) => Array<object>], 
  templates: [HierarchicalMenuTemplates], 
  cssClasses: [HierarchicalMenuCSSClasses], 
}: HierarchicalMenuWidgetOptions);

search.addWidget(widget);

Options

HierarchicalMenuWidgetOptions

• containerstring|HTMLElement

  CSS Selector or HTMLElement to insert the widget.

• attributesArray<string>

  Array of attributes to use to generate the hierarchy of the menu.

• separator[string]
  Default value: " > "

  Separator used in the attributes to separate level values.

• rootPath[string]

  Prefix path to use if the first level is not the root level.

• showParentLevel[boolean]
  Default value: true

  Show the siblings of the selected parent level of the current refined value. This

• limit[number]
  Default value: 10

  Max number of values to display.

• showMore[boolean]
  Default value: false

  Whether to display the “show more” button.

• showMoreLimit[number]
  Default value: 20

  Max number of values to display when showing more. does not impact the root level.

  The hierarchical menu is able to show or hide the siblings with showParentLevel.

  With showParentLevel set to true (default):

  • Parent lvl0
    • lvl1
      • lvl2
      • lvl2
      • lvl2
    • lvl 1
    • lvl 1
  • Parent lvl0
  • Parent lvl0

  With showParentLevel set to false:

  • Parent lvl0
    • lvl1
      • lvl2
  • Parent lvl0
  • Parent lvl0
• 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.

• templates[HierarchicalMenuTemplates]

  Templates to use for the widget.

• cssClasses[HierarchicalMenuCSSClasses]

  CSS classes to add to the wrapping elements.

HierarchicalMenuTemplates

• item[string|(object) => string]

  Item template, provided with name, count, isRefined, url data properties.

• showMoreText[string|function]

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

HierarchicalMenuCSSClasses

• 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.

• childList[string|Array<string>]

  CSS class to add to the child 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.

• parentItem[string|Array<string>]

  CSS class to add to each parent 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 element.

• disabledShowMore[string|Array<string>]

  CSS class to add to the disabled show more element.

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.hierarchicalMenu({
    container: '#hierarchical-categories',
    attributes: ['hierarchicalCategories.lvl0', 'hierarchicalCategories.lvl1', 'hierarchicalCategories.lvl2'],
  })
);

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