API Reference / React InstantSearch Hooks / <Breadcrumb>

<Breadcrumb>

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

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

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('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');

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

Props # A

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

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