> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# breadcrumb

> Shows a navigation path based on hierarchical facets.

export const Records = () => <Tooltip tip="A record is a searchable object in an Algolia index. Each record consists of named attributes." cta="Algolia records" href="/doc/guides/sending-and-managing-data/prepare-your-data#algolia-records">
    records
  </Tooltip>;

```ts Signature theme={"system"}
breadcrumb({
  container: string | HTMLElement,
  attributes: string[],
  // Optional parameters
  rootPath?: string,
  separator?: string,
  templates?: object,
  cssClasses?: object,
  transformItems?: function,
});
```

## Import

<CodeGroup>
  ```js Package manager theme={"system"}
  import { breadcrumb } from "instantsearch.js/es/widgets";
  ```

  ```js CDN theme={"system"}
  const { breadCrumb } = instantsearch.widgets;
  // or directly use instantsearch.widgets.breadcrumb()
  ```
</CodeGroup>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/js/?path=/story/metadata-breadcrumb--default" horizontal>
  Preview this widget and its behavior.
</Card>

## About this widget

The `breadcrumb` widget is a secondary navigation scheme that lets users 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:

```json JSON icon=braces theme={"system"}
[
  {
    "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 JSON icon=braces theme={"system"}
[
  {
    "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](/doc/guides/managing-results/refine-results/faceting#hierarchical-facets)
2. Determine your [`attributes`](#param-attributes) for faceting from the [dashboard](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting-with-dashboard) or with an [API client](/doc/guides/managing-results/refine-results/faceting/how-to/declaring-attributes-for-faceting)
3. Display the UI with the hierarchical menu widget.

For more information, see [Facet display](/doc/guides/building-search-ui/ui-and-ux-patterns/facet-display/js).
By default, the separator is `>` (with spaces),
but you can use a different one by using the [separator](#param-separator) option.

If there is also a [`hierarchicalMenu`](/doc/api-reference/widgets/hierarchical-menu/js) on the page,
it must follow the same configuration.

## Examples

```js JavaScript icon=code theme={"system"}
breadcrumb({
  container: "#breadcrumb",
  attributes: [
    "hierarchicalCategories.lvl0",
    "hierarchicalCategories.lvl1",
    "hierarchicalCategories.lvl2",
  ],
});
```

## Options

<ParamField body="container" type="string | HTMLElement" required>
  The CSS Selector or `HTMLElement` to insert the widget into.

  <CodeGroup>
    ```js string theme={"system"}
    breadcrumb({
      // ...
      container: "#breadcrumb",
    });
    ```

    ```js HTMLElement theme={"system"}
    breadcrumb({
      // ...
      container: document.querySelector("#breadcrumb"),
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="attributes" type="string[]" required>
  An array of attributes to generate the breadcrumb.

  ```js JavaScript icon=code theme={"system"}
  breadcrumb({
    // ...
    attributes: [
      "hierarchicalCategories.lvl0",
      "hierarchicalCategories.lvl1",
      "hierarchicalCategories.lvl2",
    ],
  });
  ```
</ParamField>

<ParamField body="rootPath" type="string">
  The path to use if the first level is not the root level.

  Make sure to also include the root path in your [UI state](/doc/api-reference/widgets/ui-state/js),
  for example, by setting [`initialUiState`](/doc/api-reference/widgets/instantsearch/js#param-initial-ui-state)
  or calling [`setUiState()`](/doc/api-reference/widgets/instantsearch/js#param-set-ui-state).

  ```js JavaScript icon=code theme={"system"}
  instantsearch({
    // ...
    initialUiState: {
      YourIndexName: {
        // breadcrumbs share their UI state with hierarchical menus
        hierarchicalMenu: {
          "hierarchicalCategories.lvl0": ["Audio"],
        },
      },
    },
  }).addWidgets([
    breadcrumb({
      // ...
      rootPath: "Audio",
    }),
  ]);
  ```
</ParamField>

<ParamField body="separator" type="string" default=" > ">
  The level separator used in the <Records />.

  ```js JavaScript icon=code theme={"system"}
  breadcrumb({
    // ...
    separator: " / ",
  });
  ```
</ParamField>

<ParamField body="templates" type="object">
  The [templates](#templates) to use for the widget.

  ```js JavaScript icon=code theme={"system"}
  breadcrumb({
    // ...
    templates: {
      // ...
    },
  });
  ```
</ParamField>

<ParamField body="cssClasses" type="object">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):

  * `root`. The root element of the widget.
  * `noRefinementRoot`. The root element if there are no refinements.
  * `list`. The list of results.
  * `item`. The list items. They contain the link and separator.
  * `selectedItem`. The selected item in the list. This is the last one, or the root one if there are no refinements.
  * `separator`. The separator.
  * `link`. The links in each item.

  ```js JavaScript icon=code theme={"system"}
  breadcrumb({
    // ...
    cssClasses: {
      root: "MyCustomBreadcrumb",
      list: ["MyCustomBreadcrumbList", "MyCustomBreadcrumbList--sub-class"],
    },
  });
  ```
</ParamField>

<ParamField body="transformItems" type="function">
  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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
  and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
  such as `disjunctiveFacetsRefinements`.

  ```js JavaScript icon=code theme={"system"}
  breadcrumb({
    // ...
    transformItems(items) {
      return items.map((item) => ({
        ...item,
        label: item.label.toUpperCase(),
      }));
    },
  });

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

## Templates

You can customize parts of a widget’s UI using the Templates API.

Each template includes an `html` function,
which you can use as a [tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).

<Note>
  The `html` function is available in InstantSearch.js version 4.46.0 or later.
</Note>

<ParamField body="home" type="string | function">
  The label of the breadcrumb's first element.

  <CodeGroup>
    ```js function theme={"system"}
    breadcrumb({
      // ...
      templates: {
        home(data, { html }) {
          return html`<span>Home</span>`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    breadcrumb({
      // ...
      templates: {
        home: "Home",
      },
    });
    ```
  </CodeGroup>
</ParamField>

<ParamField body="separator" type="string | function">
  The symbol used to separate the elements of the breadcrumb.

  <CodeGroup>
    ```js function theme={"system"}
    breadcrumb({
      // ...
      templates: {
        separator(data, { html }) {
          return html`<span> > </span>`;
        },
      },
    });
    ```

    ```js string theme={"system"}
    // String-based templates are deprecated, use functions instead.
    breadcrumb({
      // ...
      templates: {
        separator: ">",
      },
    });
    ```
  </CodeGroup>
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<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>
```

## Customize the UI with `connectBreadcrumb`

If you want to create your own UI of the `breadcrumb` widget, you can use connectors.

To use `connectBreadcrumb`, you can import it with the declaration relevant to how you installed InstantSearch.js.

<CodeGroup>
  ```js Package manager theme={"system"}
  import { connectBreadcrumb } from "instantsearch.js/es/connectors";
  ```

  ```js CDN theme={"system"}
  const { connectBreadcrumb } = instantsearch.connectors;
  // or directly use instantsearch.connectors.connectBreadcrumb()
  ```
</CodeGroup>

Then it's a 3-step process:

```js JavaScript icon=code theme={"system"}
// 1. Create a render function
const renderBreadcrumb = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customBreadcrumb = connectBreadcrumb(renderBreadcrumb);

// 3. Instantiate
search.addWidgets([
  customBreadcrumb({
    // Widget parameters
  }),
]);
```

### Create a render function

This rendering function is called before the first search (`init` lifecycle step)
and each time results come back from Algolia (`render` lifecycle step).

```js JavaScript icon=code theme={"system"}
const renderBreadcrumb = (renderOptions, isFirstRender) => {
  const { items, canRefine, refine, createURL, widgetParams } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
};
```

<Note>
  If SEO is important for your search page, ensure that your custom HTML is optimized for search engines:

  * Use `<a>` tags with `href` attributes to allow search engine bots to follow links.
  * Use semantic HTML and include [structured data](https://developers.google.com/search/docs/appearance/structured-data) when relevant.

  For more guidance, see the [SEO checklist](/doc/guides/building-search-ui/resources/seo/js).
</Note>

#### Render options

<ParamField body="items" type="object[]" required>
  The items to render, containing the keys:

  * `label`. The label of the category or subcategory.
  * `value`. The value of breadcrumb item.

  ```js JavaScript icon=code theme={"system"}
  const renderBreadcrumb = (renderOptions, isFirstRender) => {
    const { items } = renderOptions;

    document.querySelector("#breadcrumb").innerHTML = `
      <ul>
        ${items.map((item) => `<li>${item.label}</li>`).join("")}
      </ul>
    `;
  };
  ```
</ParamField>

<ParamField body="canRefine" type="boolean" required>
  Indicates if search state can be refined.

  ```js JavaScript icon=code theme={"system"}
  const renderBreadcrumb = (renderOptions, isFirstRender) => {
    const { items, canRefine, refine } = renderOptions;

    const container = document.querySelector("#breadcrumb");
    if (!canRefine) {
      container.innerHTML = "";
      return;
    }
  };
  ```
</ParamField>

<ParamField name="refine" type="function" post={["default: (item.value) => undefined"]} required>
  Sets the path of the hierarchical filter and triggers a new search.

  ```js JavaScript icon=code theme={"system"}
  const renderBreadcrumbItem = (item) => `
    <li>
      ${
        item.value
          ? `<a href="#" data-value="${item.value}">${item.label}</a>`
          : `<span>${item.label}</span>`
      }
    </li>`;

  const renderBreadcrumb = (renderOptions, isFirstRender) => {
    const { items, refine } = renderOptions;

    const container = document.querySelector("#breadcrumb");

    container.innerHTML = `
      <ul>
        <li>
          <a href="#" data-value="">Home</a>
        </li>
        ${items.map(renderBreadcrumbItem).join("")}
      </ul>
    `;

    [...container.querySelectorAll("a")].forEach((element) => {
      element.addEventListener("click", (event) => {
        event.preventDefault();
        refine(event.currentTarget.dataset.value);
      });
    });
  };
  ```
</ParamField>

<ParamField name="createURL" type="function" post={["default: (item.value) => string"]} required>
  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.

  ```js JavaScript icon=code theme={"system"}
  const renderBreadcrumb = (renderOptions, isFirstRender) => {
    const { items, createURL } = renderOptions;

    document.querySelector("#breadcrumb").innerHTML = `
      <ul>
        ${items
          .map(
            (item) =>
              `<li>
                <a href="${createURL(item.value)}">${item.label}</a>
              </li>`,
          )
          .join("")}
      </ul>
    `;
  };
  ```
</ParamField>

<ParamField body="widgetParams" type="object">
  All original widget options forwarded to the render function.

  ```js JavaScript icon=code theme={"system"}
  const renderBreadcrumb = (renderOptions, isFirstRender) => {
    const { widgetParams } = renderOptions;

    widgetParams.container.innerHTML = "...";
  };

  // ...

  search.addWidgets([
    customBreadcrumb({
      // ...
      container: document.querySelector("#breadcrumb"),
    }),
  ]);
  ```
</ParamField>

### Create and instantiate the custom widget

First, create your custom widgets using a rendering function.
Then, instantiate them with parameters.

There are two kinds of parameters you can pass:

* **Instance parameters**. Predefined options that configure Algolia's behavior.
* **Custom parameters**. Parameters you define to make the widget reusable and adaptable.

Inside the `renderFunction`, both instance and custom parameters are accessible through `connector.widgetParams`.

```js JavaScript icon=code theme={"system"}
const customBreadcrumb = connectBreadcrumb(renderBreadcrumb);

search.addWidgets([
  customBreadcrumb({
    attributes,
    // Optional instance params
    rootPath,
    separator,
    transformItems,
  }),
]);
```

#### Instance options

<ParamField body="attributes" type="string[]" required>
  The attributes to use to generate the hierarchy of the breadcrumb.

  ```js JavaScript icon=code theme={"system"}
  customBreadcrumb({
    attributes: [
      "hierarchicalCategories.lvl0",
      "hierarchicalCategories.lvl1",
      "hierarchicalCategories.lvl2",
    ],
  });
  ```
</ParamField>

<ParamField body="rootPath" type="string">
  The path to use if the first level is not the root level.

  Make sure to also include the root path in your [UI state](/doc/api-reference/widgets/ui-state/js),
  for example, by setting [`initialUiState`](/doc/api-reference/widgets/instantsearch/js#param-initial-ui-state)
  or calling [`setUiState()`](/doc/api-reference/widgets/instantsearch/js#param-set-ui-state).

  ```js JavaScript icon=code theme={"system"}
  customBreadcrumb({
    // ...
    rootPath: "Audio",
  });
  ```
</ParamField>

<ParamField body="separator" type="string" default="  > ">
  The level separator used in the records.

  ```js JavaScript icon=code theme={"system"}
  customBreadcrumb({
    // ...
    separator: " / ",
  });
  ```
</ParamField>

<ParamField body="transformItems" type="function">
  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](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
  and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
  such as `disjunctiveFacetsRefinements`.

  ```js JavaScript icon=code theme={"system"}
  customBreadcrumb({
    // ...
    transformItems(items) {
      return items.map((item) => ({
        ...item,
        label: item.label.toUpperCase(),
      }));
    },
  });

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

### Full example

<CodeGroup>
  ```html HTML theme={"system"}
  <div id="breadcrumb"></div>
  ```

  ```js JavaScript theme={"system"}
  // Create the render function
  const renderBreadcrumbItem = ({ item, createURL }) => `
    <li>
      ${
        item.value
          ? `<a
              href="${createURL(item.value)}"
              data-value="${item.value}"
            >
              ${item.label}
            </a>`
          : `<span>${item.label}</span>`
      }
    </li>`;

  const renderBreadcrumb = (renderOptions, isFirstRender) => {
    const { items, refine, createURL, widgetParams } = renderOptions;

    widgetParams.container.innerHTML = `
      <ul>
        <li>
          <a href="#" data-value="">Home</a>
        </li>
        ${items
          .map((item) =>
            renderBreadcrumbItem({
              item,
              createURL,
            }),
          )
          .join("")}
      </ul>
    `;

    [...widgetParams.container.querySelectorAll("a")].forEach((element) => {
      element.addEventListener("click", (event) => {
        event.preventDefault();
        refine(event.currentTarget.dataset.value);
      });
    });
  };

  // Create the custom widget
  const customBreadcrumb = connectBreadcrumb(renderBreadcrumb);

  // Instantiate the custom widget
  search.addWidgets([
    customBreadcrumb({
      container: document.querySelector("#breadcrumb"),
      attributes: [
        "hierarchicalCategories.lvl0",
        "hierarchicalCategories.lvl1",
        "hierarchicalCategories.lvl2",
      ],
    }),
  ]);
  ```
</CodeGroup>