Breadcrumb

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',
  ]}
/>

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

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

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

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

1
2
3
4
5
6
7
8
<CustomBreadcrumb
  attributes={[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]}
/>

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

1
2
3
4
5
6
7
8
<CustomBreadcrumb
  attributes={[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]}
/>

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>