API Reference / React InstantSearch Widgets / Breadcrumb
Apr. 24, 2019

Breadcrumb

Widget signature
<Breadcrumb
  attributes={string[]}
  // Optional parameters
  separator={React.Node}
  rootURL={string}
  transformItems={function}
  translations={object}
/>

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.

If you want to select a specific refinement for your Breadcrumb component, you need to use a Virtual Hierarchical Menu and set its defaultRefinement that is then used by the Breadcrumb.

Requirements

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

1
2
3
4
5
{
  "categories.lvl0": "products",
  "categories.lvl1": "products > fruits",
  "categories.lvl2": "products > fruits > citrus"
}

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

1
2
3
4
{
  "categories.lvl0": ["products", "goods"],
  "categories.lvl1": ["products > fruits", "goods > to eat"]
}

The attributes provided to the widget must be added in attributes for faceting, either on the dashboard or using attributesForFaceting with the API. By default, the expected separator is > (with surrounding spaces) but you can use a different one by using the separator option.

Examples

1
2
3
4
5
6
7
8
9
10
import { Breadcrumb } from 'react-instantsearch-dom';

<Breadcrumb
  attributes={[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]}
/>

Props

attributes
type: string[]
Required

A list of attributes to use to generate the hierarchy of the widget.

1
2
3
4
5
6
7
8
<Breadcrumb
  attributes={[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]}
/>
separator
type: React.Node
default: >
Optional

The character used to separate the elements of the breadcrumb.

1
2
3
4
<Breadcrumb
  // ...
  separator={<span> - </span>}
/>
rootURL
type: string
Optional

The URL (used in the href attribute) for the root element of the widget. By default, clicking on the root element removes all hierarchical refinements.

1
2
3
4
<Breadcrumb
  // ...
  rootURL="/home"
/>
transformItems
type: function
default: x => x
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.

1
2
3
4
5
6
7
8
9
<Breadcrumb
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>
translations
type: object
Optional

A mapping of keys to translation values.

  • rootLabel: Label for the root element of the widget.
1
2
3
4
5
6
<Breadcrumb
  // ...
  translations={{
    rootLabel: 'Home',
  }}
/>

Customize the UI - connectBreadcrumb

If you want to create your own UI of the Breadcrumb widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

It’s a 3-step process:

// 1. Create a React component
const Breadcrumb = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomBreadcrumb = connectBreadcrumb(Breadcrumb);

// 3. Use your connected widget
<CustomBreadcrumb />

Create a React component

const Breadcrumb = ({
  object[] items,
  function refine,
  function createURL,
}) => {
  // return the DOM output
};

Provided Props

items
type: object[]

The list of items the widget can display, with each item:

  • label: string: the label of the item.
  • value: string: the value for the item.
1
2
3
4
5
6
7
8
9
const Breadcrumb = ({ items }) => (
  <ul>
    {items.map(item => (
      <li key={item.value}>
        <a href="#">{item.label}</a>
      </li>
    ))}
  </ul>
);
refine
type: function

Clears the refinements.

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
const Breadcrumb = ({ items, refine }) =>
  Boolean(items.length) && (
    <ul>
      <li>
        <a
          href="#"
          onClick={event => {
            event.preventDefault();
            refine();
          }}
        >
          Home
        </a>
      </li>
      {items.map(item => (
        <li key={item.value}>
          <a
            href="#"
            onClick={event => {
              event.preventDefault();
              refine(item.value);
            }}
          >
            {item.label}
          </a>
        </li>
      ))}
    </ul>
  );
createURL
type: function

Generates a URL for the corresponding search state.

1
2
3
4
5
6
7
8
9
10
11
12
13
const Breadcrumb = ({ items, createURL }) =>
  Boolean(items.length) && (
    <ul>
      <li>
        <a href={createURL()}>Home</a>
      </li>
      {items.map(item => (
        <li key={item.value}>
          <a href={createURL(item.value)}>{item.label}</a>
        </li>
      ))}
    </ul>
  );

Create and instantiate your connected widget

<CustomBreadcrumb
  attributes={string[]}
  // Optional parameters
  transformItems={function}
/>

Exposed Props

attributes
type: string[]
Required

A list of attributes to use to generate the hierarchy of the widget.

1
2
3
4
5
6
7
8
<CustomBreadcrumb
  attributes={[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]}
/>
transformItems
type: function
default: x => x
Optional

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.

1
2
3
4
5
6
7
8
9
<CustomBreadcrumb
  // ...
  transformItems={items =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
/>

Full example

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
import { connectBreadcrumb } from 'react-instantsearch-dom';

const Breadcrumb = ({ items, refine, createURL }) =>
  Boolean(items.length) && (
    <ul>
      <li>
        <a
          href={createURL()}
          onClick={event => {
            event.preventDefault();
            refine();
          }}
        >
          Home
        </a>
      </li>
      {items.map(item => (
        <li key={item.value}>
          <a
            href={createURL(item.value)}
            onClick={event => {
              event.preventDefault();
              refine(item.value);
            }}
          >
            {item.label}
          </a>
        </li>
      ))}
    </ul>
  );

const CustomBreadcrumb = connectBreadcrumb(Breadcrumb);

HTML output

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?