Breadcrumb

Shows a navigation path based on hierarchical facets.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

<Breadcrumb
  attributes={string[]}
  // Optional parameters
  rootPath={string}
  separator={string}
  transformItems={function}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { Breadcrumb } from "react-instantsearch";

View demo

About this widget

<Breadcrumb> is a widget that displays navigation links 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 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.

You can also create your own UI with useBreadcrumb.

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:

1. Decide on an appropriate facet hierarchy
2. Determine your attributes for faceting from the dashboard or with an API client
3. 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

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, Breadcrumb } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <Breadcrumb
        attributes={["categories.lvl0", "categories.lvl1", "categories.lvl2"]}
      />
    </InstantSearch>
  );
}

Props

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 isn’t 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"],
      },
    },
  }}
>
  <Breadcrumb
    // ...
    rootPath="Audio"
  />
</InstantSearch>;

separator · string · default: " > "

The level separator used in the records.

JavaScript

<Breadcrumb
  // ...
  separator=" / "
/>;

transformItems · (items: object[], metadata: { results: SearchResults }) => object[]

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

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

function Search() {
  return (
    <Breadcrumb
      // ...
      transformItems={transformItems}
    />
  );
}

classNames · Partial<BreadcrumbClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

• root. The root element of the widget.
• noRefinementRoot. The root element when there are no refinements.
• list. The list element.
• item. Each item element.
• selectedItem. The selected item element.
• separator. The separator between items.
• link. The link of each item.

JavaScript

<Breadcrumb
  // ...
  classNames={{
    root: "MyBreadcrumb",
    item: "MyBreadcrumbItem MyBreadcrumbItem--subclass",
  }}
/>;

translations · Partial<BreadcrumbTranslations>

A dictionary of translations to customize the UI text and support internationalization.

• rootElementText. The text for the breadcrumb’s starting point (for example, “Home page”).

JavaScript

<Breadcrumb
  // ...
  translations={{
    rootElementText: "Index",
  }}
/>;

...props · React.ComponentProps<'div'>

Any <div> prop to forward to the root element of the widget.

JavaScript

<Breadcrumb
  // ...
  className="MyCustomBreadcrumb"
  title="My custom title"
/>;

Hook

React InstantSearch lets you create your own UI for the <Breadcrumb> widget with useBreadcrumb. Hooks provide APIs to access the widget state and interact with InstantSearch.

The useBreadcrumb Hook accepts parameters and returns APIs. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useBreadcrumb } from "react-instantsearch";

function CustomBreadcrumb(props) {
  const { items, canRefine, refine, createURL } = useBreadcrumb(props);

  return <>{/* Your JSX */}</>;
}

Then, render the widget:

JavaScript

<CustomBreadcrumb {...props} />;

Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

attributes · string[] · required

An array of attributes to generate the breadcrumb.

JavaScript

const breadcrumbApi = useBreadcrumb({
  attributes: [
    "hierarchicalCategories.lvl0",
    "hierarchicalCategories.lvl1",
    "hierarchicalCategories.lvl2",
  ],
});

rootPath · string

The path to use if the first level isn’t the root level.

Make sure to also include the root path in your UI state, for example, by setting initialUiState or calling setUiState.

JavaScript

const breadcrumbApi = useBreadcrumb({
  // ...
  rootPath: "Audio",
});

separator · string · default: " > "

The level separator used in the records.

JavaScript

const breadcrumbApi = useBreadcrumb({
  // ...
  separator: " / ",
});

transformItems · (items: object[], metadata: { results: SearchResults }) => object[]

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

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

function Breadcrumb() {
  const breadcrumbApi = useBreadcrumb({
    // ...
    transformItems,
  });

  return <>{/* Your JSX */}</>;
}

APIs

items · BreadcrumbItem[]

The list of available options, with each option:

• label: string. The label of the category or subcategory.
• value: string. The value of breadcrumb item.

TypeScript

type BreadcrumbItem = {
  value: string;
  label: string;
};

canRefine · boolean

Indicates if search state can be refined.

refine · (value: string | null) => string

Sets the path of the hierarchical filter and triggers a new search.

createURL · (value: string | null) => string

Generates a URL of the next state of a clicked item. The special value null is used for the root item of the breadcrumb and returns an empty URL.

Example

JavaScript

import React from "react";
import { useBreadcrumb } from "react-instantsearch";

function CustomBreadcrumb(props) {
  const { items, refine, createURL } = useBreadcrumb(props);

  function createOnClick(value) {
    return function onClick(event) {
      if (!isModifierClick(event)) {
        event.preventDefault();
        refine(value);
      }
    };
  }

  return (
    <ul>
      <li>
        <a href={createURL(null)} onClick={createOnClick(null)}>
          Home
        </a>
      </li>

      {items.map((item, index) => {
        const isLast = index === items.length - 1;

          <li key={index}>
            <span aria-hidden="true">&gt;</span>

            {isLast ? (
              item.label
            ) : (
              <a
                href={createURL(item.value)}
                onClick={createOnClick(item.value)}
              >
                {item.label}
              </a>
            )}
          </li>
        );
      })}
    </ul>
  );
}

function isModifierClick(event) {
  const isMiddleClick = event.button === 1;
  return Boolean(
    isMiddleClick ||
      event.altKey ||
      event.ctrlKey ||
      event.metaKey ||
      event.shiftKey
  );
}