widgets breadcrumb

Description

The breadcrumb widget is a secondary navigation scheme that allows the user to see where the current page is in relation to the facet’s hierarchy.

It reduces the number of actions a user needs to take in order to get to a higher-level page and improve the discoverability of the app or website’s sections and pages. It is commonly used for websites with a large amount of data organized into categories with subcategories.

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

Requirements

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

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

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

{
  "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.breadcrumb({ 
  container: string|HTMLElement, 
  attributes: Array<string>, 
  separator: [string], 
  rootPath: [string], 
  templates: [BreadcrumbTemplates], 
  transformItems: [(Array<object>) => Array<object>], 
  cssClasses: [BreadcrumbCSSClasses], 
}: BreadcrumbWidgetOptions);

search.addWidget(widget);

Options

BreadcrumbWidgetOptions

• containerstring|HTMLElement

  CSS Selector or HTMLElement to insert the widget.

• attributesArray<string>

  Array of attributes to use to generate the breadcrumb.

• separator[string]
  Default value: ' > '

  The level separator used in the records.

• rootPath[string]
  Default value: null

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

• templates[BreadcrumbTemplates]

  Templates to use for the widget.

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

  Function to transform the items passed to the templates.

• cssClasses[BreadcrumbCSSClasses]

  CSS classes to add to the wrapping elements.

BreadcrumbTemplates

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

  Label of the breadcrumb’s first element.

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

  Symbol used to separate the elements of the breadcrumb.

BreadcrumbCSSClasses

• root[string|Array<string>]

  CSS class to add to the root element of the widget.

• noRefinementRoot[string|Array<string>]

  CSS class to add to the root element of the widget if there are no refinements.

• list[string|Array<string>]

  CSS class to add to the list element.

• item[string|Array<string>]

  CSS class to add to the items of the list. The items contains the link and the separator.

• selectedItem[string|Array<string>]

  CSS class to add to the selected item in the list: the last one or the home if there are no refinements.

• separator[string|Array<string>]

  CSS class to add to the separator.

• link[string|Array<string>]

  CSS class to add to the links in the items.

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.breadcrumb({
    container: '#breadcrumb',
    attributes: ['hierarchicalCategories.lvl0', 'hierarchicalCategories.lvl1', 'hierarchicalCategories.lvl2'],
    templates: { home: 'Home Page' },
    separator: ' / ',
    rootPath: 'Cameras & Camcorders > Digital Cameras',
  })
);

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