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

# ais-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>;

```vue Signature theme={"system"}
<ais-breadcrumb
  :attributes="string[]"
  // Optional parameters
  root-path="string"
  separator="string"
  :transform-items="function"
  :class-names="object"
/>
```

## Import

<Tabs>
  <Tab title="Component">
    To ensure optimal bundle sizes,
    see [Optimize build size](/doc/guides/building-search-ui/going-further/improve-performance/vue#optimize-build-size).

    ```js Vue icon=code theme={"system"}
    import { AisBreadcrumb } from "vue-instantsearch";
    // Use "vue-instantsearch/vue3/es" for Vue 3

    export default {
      components: {
        AisBreadcrumb
      },
      // ...
    };
    ```
  </Tab>

  <Tab title="Plugin">
    This imports all widgets, even the ones you don't use.
    For more information, see [Get started with Vue InstantSearch](/doc/guides/building-search-ui/getting-started/vue).

    ```js JavaScript icon="code" theme={"system"}
    import Vue from "vue";
    import InstantSearch from "vue-instantsearch";
    // Use "vue-instantsearch/vue3/es" for Vue 3

    Vue.use(InstantSearch);
    ```
  </Tab>
</Tabs>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/vue/?selectedKind=ais-breadcrumb" horizontal>
  Preview this widget and its behavior.
</Card>

## About this widget

The `ais-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 lots of data,
organized into categories with subcategories.

### Requirements

Breadcrumbs objects must have 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/vue).
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 [`ais-hierarchical-manu`](/doc/api-reference/widgets/hierarchical-menu/vue) on the page,
it must follow the same configuration.

## Examples

```vue Vue icon=code theme={"system"}
<ais-breadcrumb
  :attributes="[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]"
/>
```

## Props

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

  <Note>
    To [prevent creating infinite loops](https://support.algolia.com/hc/en-us/articles/4406511683217-Vue-InstantSearch-How-do-I-prevent-infinite-loops),
    avoid passing arrays, objects, or functions directly in the template.
    These values aren't referentially equal on each render,
    which causes the widget to re-register every time.
    Instead, define them in your component's `data` option and reference them in the template.
  </Note>

  ```vue Vue icon=code theme={"system"}
  <ais-breadcrumb
    :attributes="[
      'categories.lvl0',
      'categories.lvl1',
      'categories.lvl2',
      'categories.lvl3',
    ]"
  />
  ```
</ParamField>

<ParamField body="root-path" 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/vue),
  for example, by setting [`initial-ui-state`](/doc/api-reference/widgets/instantsearch/vue#param-initial-ui-state).

  ```vue Vue icon=code theme={"system"}
  <ais-instant-search
    [...]
    :initial-ui-state="{
      YourIndexName: {
        // breadcrumbs share their UI state with hierarchical menus
        hierarchicalMenu: {
          'categories.lvl0': ['Audio > Home Audio'],
        },
      },
    }"
  >
    <ais-breadcrumb
      [...]
      root-path="Audio > Home Audio"
    />
  </ais-instant-search>
  ```
</ParamField>

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

  ```vue Vue icon=code theme={"system"}
  <ais-breadcrumb
      [...] 
      separator="-" 
  />
  ```
</ParamField>

<ParamField body="transform-items" 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`.

  ```vue Vue icon=code theme={"system"}
  <template>
    <!-- ... -->
    <ais-breadcrumb 
      [...] 
      :transform-items="transformItems" 
    />
  </template>

  <script>
  export default {
    methods: {
      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)`,
          },
        ];
      },
    },
  };
  </script>
  ```
</ParamField>

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

  * `ais-Breadcrumb`. The root element of the widget.
  * `ais-Breadcrumb--noRefinement`. The root element of the widget with no refinement.
  * `ais-Breadcrumb-list`. The list of all breadcrumb items.
  * `ais-Breadcrumb-item`. The breadcrumb navigation item.
  * `ais-Breadcrumb-item--selected`. The selected breadcrumb item.
  * `ais-Breadcrumb-separator`. The separator of each breadcrumb item.
  * `ais-Breadcrumb-link`. The clickable breadcrumb element.

  ```vue Vue icon=code theme={"system"}
  <ais-breadcrumb
    [...]
    :class-names="{
      'ais-Breadcrumb': 'MyCustomBreadcrumb',
      'ais-Breadcrumb-list': 'MyCustomBreadcrumbList',
    }"
  />
  ```
</ParamField>

## Customize the UI

<ParamField body="default">
  The slot to override the complete DOM output of the widget.

  Note that when you implement this slot,
  none of the other slots will change the output,
  as the default slot surrounds them.

  **Scope**

  * `items: object[]`
  * `refine: (value: string) => void`
  * `createURL: (value: string) => string`

  Where each item is an `object` containing:

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

  ```vue Vue icon=code theme={"system"}
  <ais-breadcrumb
    :attributes="[
      'categories.lvl0',
      'categories.lvl1',
      'categories.lvl2',
      'categories.lvl3',
    ]"
  >
    <template v-slot="{ items, refine, createURL }">
      <ul>
        <li>
          <a :href="createURL()" @click.prevent="refine()">Home</a>
        </li>
        <li v-for="item in items" :key="item.label">
          <a
            v-if="item.value"
            :href="createURL(item.value)"
            @click.prevent="refine(item.value)"
          >
            {{ item.label }}
          </a>
          <span v-else>{{ item.label }}</span>
        </li>
      </ul>
    </template>
  </ais-breadcrumb>
  ```
</ParamField>

<ParamField body="rootLabel">
  The slot to override the root label.

  ```vue Vue icon=code theme={"system"}
  <ais-breadcrumb
    :attributes="[
      'categories.lvl0',
      'categories.lvl1',
      'categories.lvl2',
      'categories.lvl3',
    ]"
  >
    <template v-slot:rootLabel>Home page</template>
  </ais-breadcrumb>
  ```
</ParamField>

<ParamField body="separator">
  The slot to override the separator.

  ```vue Vue icon=code theme={"system"}
  <ais-breadcrumb
    :attributes="[
      'categories.lvl0',
      'categories.lvl1',
      'categories.lvl2',
      'categories.lvl3',
    ]"
  >
    <template v-slot:separator>→</template>
  </ais-breadcrumb>
  ```
</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" aria-hidden="true">></span>
      <a class="ais-Breadcrumb-link" href="#">Cooking</a>
    </li>
    <li class="ais-Breadcrumb-item ais-Breadcrumb-item--selected">
      <span class="ais-Breadcrumb-separator" aria-hidden="true">></span>
      Kitchen textiles
    </li>
  </ul>
</div>
```

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