API Reference / React InstantSearch Hooks / <Breadcrumb>

<Breadcrumb>

Signature 
<Breadcrumb
  attributes={string[]}
  // Optional parameters
  rootPath={string}
  separator={string}
  transformItems={UseBreadcrumbProps['transformItems']}
  classNames={Partial<BreadcrumbClassNames>}
  ...props={React.ComponentProps<'div'>}
/>
See code examples
See live example

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.

Requirements

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

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

[
  {
    "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:

Copy 
1
2
3
4
5
6
7
8

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

The attributes provided to the widget must be in attributes for faceting, either on the dashboard or using attributesForFaceting with the API. 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.

You can also create your own UI with useBreadcrumb().

Examples

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

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, Breadcrumb } from 'react-instantsearch-hooks-web';

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
type: string[]
Required

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

<Breadcrumb
  attributes={[
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
  ]}
/>
rootPath
type: string
Optional

The path to use if the first level isn’t the root level.
Copy 
1
2
3
4

<Breadcrumb
  // ...
  rootPath="Audio"
/>
separator
type: string
default: >
Optional

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

<Breadcrumb
  // ...
  separator=" / "
/>
transformItems
type: BreadcrumbProps['transformItems']

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

  /* or, combined with results */
  transformItems={(items, { results }) => {
    const lastItem = items.pop();
    return [
      ...items,
      {
        ...lastItem,
        label: `${lastItem.label} (${results.nbHits} hits)`,
      },
    ];
  }}
/>
classNames
type: Partial<BreadcrumbClassNames>
Optional

CSS classes to pass to the widget’s elements. This is 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.
Copy 
1
2
3
4
5
6
7

<Breadcrumb
  // ...
  classNames={{
    root: 'MyBreadcrumb',
    item: 'MyBreadcrumbItem MyBreadcrumbItem--subclass'
  }}
/>
...props
type: React.ComponentProps<'div'>
Optional

Any <div> prop to forward to the root element of the widget.
Copy 
1
2
3
4
5

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

Hook

React InstantSearch Hooks let 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.

See code examples

Usage

First, create your React component:

import { useBreadcrumb } from 'react-instantsearch-hooks-web';

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

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

Then, render the widget:

<CustomBreadcrumb {...props} />

Parameters

Hooks accept parameters. You can pass them manually, or forward the props from your custom component.

When you provide a function to Hooks, make sure to pass a stable reference with useCallback() to avoid rendering endlessly. Objects and arrays are memoized so you don’t have to stabilize them.

attributes
type: string[]
Required

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

const breadcrumbApi = useBreadcrumb({
  attributes: [
    'hierarchicalCategories.lvl0',
    'hierarchicalCategories.lvl1',
    'hierarchicalCategories.lvl2',
  ],
});
rootPath
type: string
Optional

The path to use if the first level isn’t the root level.
Copy 
1
2
3
4

const breadcrumbApi = useBreadcrumb({
  // ...
  rootPath: 'Audio',
});
separator
type: string
default: " > "
Optional

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

const breadcrumbApi = useBreadcrumb({
  // ...
  separator: ' / ',
});
transformItems
type: UseBreadcrumbProps['transformItems']

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

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

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

APIs

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

items
type: 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.
Copy 
1
2
3
4

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

Indicates if search state can be refined.
refine
type: (value: string | null) => string

Sets the path of the hierarchical filter and triggers a new search.
createURL
type: (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

Copy 
1
2
3
4
5
6
7
8

import React from 'react';
import { useBreadcrumb } from 'react-instantsearch-hooks-web';

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

  return <>{/* Your JSX */}</>;
}
Did you find this page helpful?
React InstantSearch Hooks v6