breadcrumb

Signature

breadcrumb({
  container: string | HTMLElement,
  attributes: string[],
  // Optional parameters
  rootPath?: string,
  separator?: string,
  templates?: object,
  cssClasses?: object,
  transformItems?: function,
});

Import

import { breadcrumb } from "instantsearch.js/es/widgets";

const { breadCrumb } = instantsearch.widgets;
// or directly use instantsearch.widgets.breadcrumb()

See this widget in action

Preview this widget and its behavior.

The breadcrumb widget is a secondary navigation scheme that lets users 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’s commonly used for websites with lot of data, organized into categories with subcategories.

Requirements

The objects to use in the breadcrumb must follow this structure:

JSON

[
  {
    "objectID": "321432",
    "name": "lemon",
    "categories.lvl0": "products",
    "categories.lvl1": "products > fruits"
  },
  {
    "objectID": "8976987",
    "name": "orange",
    "categories.lvl0": "products",
    "categories.lvl1": "products > fruits"
  }
]

It’s also possible to provide more than one path for each level:

JSON

[
  {
    "objectID": "321432",
    "name": "lemon",
    "categories.lvl0": ["products", "goods"],
    "categories.lvl1": ["products > fruits", "goods > to eat"]
  }
]

To create a hierarchical menu:

Decide on an appropriate facet hierarchy
Determine your attributes for faceting from the dashboard or with an API client
Display the UI with the hierarchical menu widget.

For more information, see Facet display. By default, the separator is > (with spaces), but you can use a different one by using the separator option. If there is also a hierarchicalMenu on the page, it must follow the same configuration.

Examples

JavaScript

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

Options

container

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

breadcrumb({
  // ...
  container: "#breadcrumb",
});

breadcrumb({
  // ...
  container: document.querySelector("#breadcrumb"),
});

attributes

string[]

required

An array of attributes to generate the breadcrumb.

JavaScript

breadcrumb({
  // ...
  attributes: [
    "hierarchicalCategories.lvl0",
    "hierarchicalCategories.lvl1",
    "hierarchicalCategories.lvl2",
  ],
});

rootPath

string

The path to use if the first level is not the root level.Make sure to also include the root path in your UI state, for example, by setting initialUiState or calling setUiState().

JavaScript

instantsearch({
  // ...
  initialUiState: {
    YourIndexName: {
      // breadcrumbs share their UI state with hierarchical menus
      hierarchicalMenu: {
        "hierarchicalCategories.lvl0": ["Audio"],
      },
    },
  },
}).addWidgets([
  breadcrumb({
    // ...
    rootPath: "Audio",
  }),
]);

separator

string

default:" > "

The level separator used in the .

JavaScript

breadcrumb({
  // ...
  separator: " / ",
});

templates

object

The templates to use for the widget.

JavaScript

breadcrumb({
  // ...
  templates: {
    // ...
  },
});

cssClasses

object

The CSS classes you can 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.

JavaScript

breadcrumb({
  // ...
  cssClasses: {
    root: "MyCustomBreadcrumb",
    list: ["MyCustomBreadcrumbList", "MyCustomBreadcrumbList--sub-class"],
  },
});

transformItems

function

A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

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

// or, combined with results
breadcrumb({
  // ...
  transformItems(items, { results }) {
    const lastItem = items.pop();
    return [
      ...items,
      {
        ...lastItem,
        label: `${lastItem.label} (${results.nbHits} hits)`,
      },
    ];
  },
});

Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

home

string | function

The label of the breadcrumb’s first element.

breadcrumb({
  // ...
  templates: {
    home(data, { html }) {
      return html`<span>Home</span>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
breadcrumb({
  // ...
  templates: {
    home: "Home",
  },
});

separator

string | function

The symbol used to separate the elements of the breadcrumb.

breadcrumb({
  // ...
  templates: {
    separator(data, { html }) {
      return html`<span> > </span>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
breadcrumb({
  // ...
  templates: {
    separator: ">",
  },
});

HTML output

HTML

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

Customize the UI with `connectBreadcrumb`

If you want to create your own UI of the breadcrumb widget, you can use connectors. To use connectBreadcrumb, you can import it with the declaration relevant to how you installed InstantSearch.js.

import { connectBreadcrumb } from "instantsearch.js/es/connectors";

const { connectBreadcrumb } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectBreadcrumb()

Then it’s a 3-step process:

JavaScript

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

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

// 3. Instantiate
search.addWidgets([
  customBreadcrumb({
    // Widget parameters
  }),
]);

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

JavaScript

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

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

  // Render the widget
};

If SEO is important for your search page, ensure that your custom HTML is optimized for search engines:

Use <a> tags with href attributes to allow search engine bots to follow links.
Use semantic HTML and include structured data when relevant.

For more guidance, see the SEO checklist.

Render options

items

object[]

required

The items to render, containing the keys:

label. The label of the category or subcategory.
value. The value of breadcrumb item.

JavaScript

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

  document.querySelector("#breadcrumb").innerHTML = `
    <ul>
      ${items.map((item) => `<li>${item.label}</li>`).join("")}
    </ul>
  `;
};

canRefine

boolean

required

Indicates if search state can be refined.

JavaScript

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

  const container = document.querySelector("#breadcrumb");
  if (!canRefine) {
    container.innerHTML = "";
    return;
  }
};

All original widget options forwarded to the render function.

JavaScript

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

  widgetParams.container.innerHTML = "...";
};

// ...

search.addWidgets([
  customBreadcrumb({
    // ...
    container: document.querySelector("#breadcrumb"),
  }),
]);

First, create your custom widgets using a rendering function. Then, instantiate them with parameters. There are two kinds of parameters you can pass:

Instance parameters. Predefined options that configure Algolia’s behavior.
Custom parameters. Parameters you define to make the widget reusable and adaptable.

Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.

JavaScript

const customBreadcrumb = connectBreadcrumb(renderBreadcrumb);

search.addWidgets([
  customBreadcrumb({
    attributes,
    // Optional instance params
    rootPath,
    separator,
    transformItems,
  }),
]);

Instance options

attributes

string[]

required

The attributes to use to generate the hierarchy of the breadcrumb.

JavaScript

customBreadcrumb({
  attributes: [
    "hierarchicalCategories.lvl0",
    "hierarchicalCategories.lvl1",
    "hierarchicalCategories.lvl2",
  ],
});

rootPath

string

The path to use if the first level is not the root level.Make sure to also include the root path in your UI state, for example, by setting initialUiState or calling setUiState().

JavaScript

customBreadcrumb({
  // ...
  rootPath: "Audio",
});

separator

string

default:" > "

The level separator used in the records.

JavaScript

customBreadcrumb({
  // ...
  separator: " / ",
});

transformItems

function

JavaScript

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

// or, combined with results
customBreadcrumb({
  // ...
  transformItems(items, { results }) {
    const lastItem = items.pop();
    return [
      ...items,
      {
        ...lastItem,
        label: `${lastItem.label} (${results.nbHits} hits)`,
      },
    ];
  },
});

Full example

<div id="breadcrumb"></div>

// 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 = connectBreadcrumb(renderBreadcrumb);

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

InstantSearch.js

Import

See this widget in action

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectBreadcrumb`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example

​Import

See this widget in action

​About this widget

​Requirements

​Examples

​Options

​Templates

​HTML output

​Customize the UI with connectBreadcrumb

​Create a render function

​Render options

​Create and instantiate the custom widget

​Instance options

​Full example

Import

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with `connectBreadcrumb`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example