widgets breadcrumb

Edit this page

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

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

const widget = instantsearch.widgets.breadcrumb({ container: string|HTMLElement, attributes: Array<string>, templates: [BreadcrumbTemplates], transformData: [BreadcrumbTransforms], autoHideContainer: [boolean], cssClasses: [BreadcrumbCSSClasses], transformItems: [(Array<object>) => Array<object>], }: 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.

    You can also use a sort function that behaves like the standard Javascript compareFunction.

  • templates[BreadcrumbTemplates]

    Templates to use for the widget.

  • transformData[BreadcrumbTransforms]

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

  • autoHideContainer[boolean]
    Default value: true

    Hides the container when there are no items in the breadcrumb.

  • cssClasses[BreadcrumbCSSClasses]

    CSS classes to add to the wrapping elements.

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

    Function to transform the items passed to the templates.

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.

BreadcrumbTransforms

  • item[(object) => object]

    Method to change the object passed to the item template

BreadcrumbCSSClasses

  • disabledLabel[string|Array<string>]

    CSS class to add to the last element of the breadcrumb (which is not clickable).

  • home[string|Array<string>]

    CSS class to add to the first element of the breadcrumb.

  • label[string|Array<string>]

    CSS class to add to the text part of each element of the breadcrumb.

  • root[string|Array<string>]

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

  • separator[string|Array<string>]

    CSS class to add to the separator.

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' },
    rootPath: 'Cameras & Camcorders > Digital Cameras',
  })
);

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