widgets hierarchicalMenu

Edit this page

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

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

const widget = instantsearch.widgets.hierarchicalMenu({ container: string|HTMLElement, attributes: Array<string>, limit: [number], separator: [string], rootPath: [string], showParentLevel: [boolean], sortBy: [Array<string>|function], templates: [HierarchicalMenuTemplates], transformData: [HierarchicalMenuTransforms], autoHideContainer: [boolean], cssClasses: [HierarchicalMenuCSSClasses], collapsible: [boolean|{collapsed: boolean}], transformItems: [(Array<object>) => Array<object>], }: 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.

  • limit[number]
    Default value: 10

    How much facet values to get.

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

  • templates[HierarchicalMenuTemplates]

    Templates to use for the widget.

  • transformData[HierarchicalMenuTransforms]

    Set of functions to transform the data passed to the templates.

  • autoHideContainer[boolean]
    Default value: true

    Hide the container when there are no items in the menu.

  • cssClasses[HierarchicalMenuCSSClasses]

    CSS classes to add to the wrapping elements.

  • collapsible[boolean|{collapsed: boolean}]
    Default value: false

    Makes the widget collapsible. The user can then choose to hide the content of the widget. This option can also be an object with the property collapsed. If this property is true, then the widget is hidden during the first rendering.

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

    Function to transform the items passed to the templates.

HierarchicalMenuTemplates

  • header[string|(object) => string]
    Default value: ''

    Header template (root level only).

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

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

HierarchicalMenuTransforms

  • item[(object) => object]

    Method to change the object passed to the item. template

HierarchicalMenuCSSClasses

  • root[string|Array<string>]

    CSS class to add to the root element.

  • header[string|Array<string>]

    CSS class to add to the header element.

  • body[string|Array<string>]

    CSS class to add to the body element.

  • list[string|Array<string>]

    CSS class to add to the list element.

  • item[string|Array<string>]

    CSS class to add to each item element.

  • depth[string|Array<string>]

    CSS class to add to each item element to denote its depth. The actual level will be appended to the given class name (ie. if depth is given, the widget will add depth0, depth1, … according to the level of each item).

  • active[string|Array<string>]

    CSS class to add to each active element.

  • count[string|Array<string>]

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

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'],
    templates: {
      header: 'Hierarchical categories'
    }
  })
);

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