` prop to forward to the root element of the widget.
```jsx JavaScript icon=code theme={"system"}
;
```
## Hook
React InstantSearch lets you create your own UI for the `
` widget with `useBreadcrumb`.
Hooks provide APIs to access the widget state and interact with InstantSearch.
The `useBreadcrumb` Hook accepts [parameters](#parameters) and returns [APIs](#hook).
It must be used inside the [``](/doc/api-reference/widgets/instantsearch/react) component.
### Usage
First, create your React component:
```jsx JavaScript icon=code theme={"system"}
import { useBreadcrumb } from "react-instantsearch";
function CustomBreadcrumb(props) {
const { items, canRefine, refine, createURL } = useBreadcrumb(props);
return <>{/* Your JSX */};
}
```
Then, render the widget:
```jsx JavaScript icon=code theme={"system"}
;
```
### Parameters
Hooks accept parameters. You can either pass them manually or forward props from a custom component.
When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders.
Use [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) for memoization.
Arrays and objects are automatically memoized.
An array of attributes to generate the breadcrumb.
```js JavaScript icon=code theme={"system"}
const breadcrumbApi = useBreadcrumb({
attributes: [
"hierarchicalCategories.lvl0",
"hierarchicalCategories.lvl1",
"hierarchicalCategories.lvl2",
],
});
```
The path to use if the first level isn't the root level.
Make sure to also include the root path in your [UI state](/doc/api-reference/widgets/ui-state/react),
for example, by setting [`initialUiState`](/doc/api-reference/widgets/instantsearch/react#param-initial-ui-state)
or calling [`setUiState`](/doc/api-reference/widgets/use-instantsearch/react#param-set-ui-state).
```js JavaScript icon=code theme={"system"}
const breadcrumbApi = useBreadcrumb({
// ...
rootPath: "Audio",
});
```
The level separator used in the records.
```js JavaScript icon=code theme={"system"}
const breadcrumbApi = useBreadcrumb({
// ...
separator: " / ",
});
```
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`.
```jsx JavaScript theme={"system"}
const transformItems = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function Breadcrumb() {
const breadcrumbApi = useBreadcrumb({
// ...
transformItems,
});
return <>{/* Your JSX */};
}
```
```tsx TypeScript theme={"system"}
import type { UseBreadcrumbProps } from "react-instantsearch";
const transformItems: UseBreadcrumbProps["transformItems"] = (items) => {
return items.map((item) => ({
...item,
label: item.label.toUpperCase(),
}));
};
function Breadcrumb() {
const breadcrumbApi = useBreadcrumb({
// ...
transformItems,
});
return <>{/* Your JSX */};
}
```
### APIs
The list of available options, with each option:
* `label: string`. The label of the category or subcategory.
* `value: string`. The value of breadcrumb item.
```ts TypeScript icon=code theme={"system"}
type BreadcrumbItem = {
value: string;
label: string;
};
```
Indicates if search state can be refined.
Sets the path of the hierarchical filter and triggers a new search.
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
```jsx JavaScript theme={"system"}
import React from "react";
import { useBreadcrumb } from "react-instantsearch";
function CustomBreadcrumb(props) {
const { items, refine, createURL } = useBreadcrumb(props);
function createOnClick(value) {
return function onClick(event) {
if (!isModifierClick(event)) {
event.preventDefault();
refine(value);
}
};
}
return (
-
Home
{items.map((item, index) => {
const isLast = index === items.length - 1;
-
>
{isLast ? (
item.label
) : (
{item.label}
)}
);
})}
);
}
function isModifierClick(event) {
const isMiddleClick = event.button === 1;
return Boolean(
isMiddleClick ||
event.altKey ||
event.ctrlKey ||
event.metaKey ||
event.shiftKey
);
}
```
```tsx TypeScript theme={"system"}
import React from 'react';
import { useBreadcrumb, UseBreadcrumbProps } from 'react-instantsearch';
type BreadcrumbItem = ReturnType['items'][number];
function CustomBreadcrumb(props: UseBreadcrumbProps) {
const { items, refine, createURL } = useBreadcrumb(props);
function createOnClick(value: BreadcrumbItem['value']) {
return function onClick(
event: React.MouseEvent,
) {
if (!isModifierClick(event)) {
event.preventDefault();
refine(value);
}
};
}
return (
-
Home
{items.map((item, index) => {
const isLast = index === items.length - 1;
return (
-
>
{isLast ? (
item.label
) : (
{item.label}
)}
);
})}
);
}
function isModifierClick(event: React.MouseEvent) {
const isMiddleClick = event.button === 1;
return Boolean(
isMiddleClick ||
event.altKey ||
event.ctrlKey ||
event.metaKey ||
event.shiftKey
);
}
```