API Reference / InstantSearch.js Widgets / breadcrumb
Apr. 24, 2019

breadcrumb

Widget signature 
instantsearch.widgets.breadcrumb({
  container: string|HTMLElement,
  attributes: string[],
  // Optional parameters
  rootPath: string,
  separator: string,
  templates: object,
  cssClasses: object,
  transformItems: function,
});
See code examples
See Live example

About this widget #

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

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

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

Examples #

Copy
1
2
3
4
5
6
7
8

instantsearch.widgets.breadcrumb({
  container: '#breadcrumb',
  attributes: [
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
  ],
});

Options #

container #
type: string|HTMLElement
Required

The CSS Selector or HTMLElement to insert the widget into.
Edit
Copy 
1
2
3
4

instantsearch.widgets.breadcrumb({
  // ...
  container: '#breadcrumb',
});
attributes #
type: string[]
Required

An array of attributes to generate the breadcrumb.
Edit
Copy 
1
2
3
4
5
6
7
8

instantsearch.widgets.breadcrumb({
  // ...
  attributes: [
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
  ],
});
rootPath #
type: string
Optional

The path to use if the first level is not the root level.
Edit
Copy 
1
2
3
4

instantsearch.widgets.breadcrumb({
  // ...
  rootPath: 'Audio',
});
separator #
type: string
default: >
Optional

The level separator used in the records.
Edit
Copy 
1
2
3
4

instantsearch.widgets.breadcrumb({
  // ...
  separator: ' / ',
});
templates #
type: object
Optional

The templates to use for the widget.
Edit
Copy 
1
2
3
4
5
6

instantsearch.widgets.breadcrumb({
  // ...
  templates: {
    // ...
  },
});
cssClasses #
type: object
Optional

The CSS classes to override.

  • root: the root element of the widget.
  • noRefinementRoot: the root element if there are no refinements.
  • list: the list of results.
  • item: the list items. They contain the link and separator.
  • selectedItem: the selected item in the list. This is the last one, or the root one if there are no refinements.
  • separator: the separator.
  • link: the links in each item.
Edit
Copy 
1
2
3
4
5
6
7
8
9
10

instantsearch.widgets.breadcrumb({
  // ...
  cssClasses: {
    root: 'MyCustomBreadcrumb',
    list: [
      'MyCustomBreadcrumbList',
      'MyCustomBreadcrumbList--sub-class',
    ],
  },
});
transformItems #
type: function
Optional

A function to transform the items passed to the templates.
Edit
Copy 
1
2
3
4
5
6
7
8
9

instantsearch.widgets.breadcrumb({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

Templates #

home #
type: string|function
Optional

The label of the breadcrumb’s first element.
Edit
Copy 
1
2
3
4
5
6

instantsearch.widgets.breadcrumb({
  // ...
  templates: {
    home: 'Home',
  },
});
separator #
type: string|function
Optional

The symbol used to separate the elements of the breadcrumb.
Edit
Copy 
1
2
3
4
5
6

instantsearch.widgets.breadcrumb({
  // ...
  templates: {
    separator: '>',
  },
});

Customize the UI - connectBreadcrumb#

If you want to create your own UI of the breadcrumb widget, you can use connectors.

It’s a 3-step process:

// 1. Create a render function
const renderBreadcrumb = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customBreadcrumb = instantsearch.connectors.connectBreadcrumb(
  renderBreadcrumb
);

// 3. Instantiate
search.addWidget(
  customBreadcrumb({
    // Widget parameters
  });
);

See code examples

Create a render function#

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

const renderBreadcrumb = (renderOptions, isFirstRender) => {
  const {
    object[] items,
    function refine,
    function createURL,
    object widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
};

If SEO is critical to your search page, your custom HTML markup needs to be parsable:

  • use plain <a> tags with href attributes for search engines bots to follow them,
  • use semantic markup with structured data when relevant, and test it.

Refer to our SEO checklist for building SEO-ready search experiences.

Rendering options #

items #
type: object[]
Required

The items to render, containing the keys:

  • label: the label of the category or subcategory.
  • value: the value of breadcrumb item.
Edit
Copy 
1
2
3
4
5
6
7
8
9

const renderBreadcrumb = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

  document.querySelector('#breadcrumb').innerHTML = `
    <ul>
      ${items.map(item => `<li>${item.label}</li>`).join('')}
    </ul>
  `;
};
refine #
type: function
default: (item.value) => undefined
Required

Sets the path of the hierarchical filter and triggers a new search.
Edit
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

const renderBreadcrumbItem = item => `
  <li>
    ${
      item.value
        ? `<a href="#" data-value="${item.value}">${item.label}</a>`
        : `<span>${item.label}</span>`
    }
  </li>`;

const renderBreadcrumb = (renderOptions, isFirstRender) => {
  const { items, refine } = renderOptions;

  const container = document.querySelector('#breadcrumb');

  container.innerHTML = `
    <ul>
      <li>
        <a href="#" data-value="">Home</a>
      </li>
      ${items.map(renderBreadcrumbItem).join('')}
    </ul>
  `;

  [...container.querySelectorAll('a')].forEach(
    element => {
      element.addEventListener('click', event => {
        event.preventDefault();
        refine(event.currentTarget.dataset.value);
      });
    }
  );
};
createURL #
type: function
default: (item.value) => string
Required

Generates a URL for the next state of a clicked item. The special value null is used for the root item of the breadcrumb and returns an empty array.
Edit
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

const renderBreadcrumb = (renderOptions, isFirstRender) => {
  const { items, createURL } = renderOptions;

  document.querySelector('#breadcrumb').innerHTML = `
    <ul>
      ${items
        .map(
          item =>
            `<li>
              <a href="${createURL(item.value)}">${item.label}</a>
            </li>`
        )
        .join('')}
    </ul>
  `;
};
widgetParams #
type: object

All original widget options forwarded to the render function.
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14

const renderBreadcrumb = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = '...';
};

// ...

search.addWidget(
  customBreadcrumb({
    // ...
    container: document.querySelector('#breadcrumb'),
  })
);

Create and instantiate the custom widget#

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

  • Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
  • Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customBreadcrumb = instantsearch.connectors.connectBreadcrumb(
  renderBreadcrumb
);

search.addWidget(
  customBreadcrumb({
    attributes: string[],
    // Optional instance params
    rootPath: string,
    separator: string,
    transformItems: function,
  })
);

Instance options #

attributes #
type: string[]
Required

The attributes to use to generate the hierarchy of the breadcrumb.
Edit
Copy 
1
2
3
4
5
6
7

customBreadcrumb({
  attributes: [
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
  ],
});
rootPath #
type: string
Optional

The path to use if the first level is not the root level.
Edit
Copy 
1
2
3
4

customBreadcrumb({
  // ...
  rootPath: 'Audio',
});
separator #
type: string
default: >
Optional

The level separator used in the records.
Edit
Copy 
1
2
3
4

customBreadcrumb({
  // ...
  separator: ' / ',
});
transformItems #
type: function
Optional

A function to transform the items passed to the templates.
Edit
Copy 
1
2
3
4
5
6
7
8
9

customBreadcrumb({
  // ...
  transformItems(items) {
    return items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },
});

Full example#

Edit
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

// Create the render function
const renderBreadcrumbItem = ({ item, createURL }) => `
  <li>
    ${
      item.value
        ? `<a
            href="${createURL(item.value)}"
            data-value="${item.value}"
          >
            ${item.label}
          </a>`
        : `<span>${item.label}</span>`
    }
  </li>`;

const renderBreadcrumb = (renderOptions, isFirstRender) => {
  const { items, refine, createURL, widgetParams } = renderOptions;

  widgetParams.container.innerHTML = `
    <ul>
      <li>
        <a href="#" data-value="">Home</a>
      </li>
      ${items
        .map(item =>
          renderBreadcrumbItem({
            item,
            createURL,
          })
        )
        .join('')}
    </ul>
  `;

  [...widgetParams.container.querySelectorAll('a')].forEach(element => {
    element.addEventListener('click', event => {
      event.preventDefault();
      refine(event.currentTarget.dataset.value);
    });
  });
};

// Create the custom widget
const customBreadcrumb = instantsearch.connectors.connectBreadcrumb(
  renderBreadcrumb
);

// Instantiate the custom widget
search.addWidget(
  customBreadcrumb({
    container: document.querySelector('#breadcrumb'),
    attributes: [
      'hierarchicalCategories.lvl0',
      'hierarchicalCategories.lvl1',
      'hierarchicalCategories.lvl2',
    ],
  })
);

HTML output#

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<div class="ais-Breadcrumb">
  <ul class="ais-Breadcrumb-list">
    <li class="ais-Breadcrumb-item">
      <a class="ais-Breadcrumb-link" href="#">Home</a>
    </li>
    <li class="ais-Breadcrumb-item">
      <span class="ais-Breadcrumb-separator"> &gt; </span>
      <a class="ais-Breadcrumb-link" href="#">Cameras &amp; Camcorders</a>
    </li>
    <li class="ais-Breadcrumb-item ais-Breadcrumb-item--selected">
      <span class="ais-Breadcrumb-separator"> &gt; </span>
      Digital Cameras
    </li>
  </ul>
</div>

Did you find this page helpful?

InstantSearch.js v3