UI libraries / Vue InstantSearch / Widgets

ais-breadcrumb

Signature 
<ais-breadcrumb
  :attributes="string[]"
  // Optional parameters
  root-path="string"
  separator="string"
  :transform-items="function"
  :class-names="object"
/>
Import
Copy 
1
2
3
4
5
6
7
8
9

import { AisBreadcrumb } from 'vue-instantsearch';
// Use 'vue-instantsearch/vue3/es' for Vue 3

export default {
  components: {
    AisBreadcrumb
  },
  // ...
};

1. Follow additional steps in Optimize build size to ensure your code is correctly bundled.
2. This imports all the widgets, even the ones you don’t use. Read the Getting started guide for more information.

See code examples
See live example

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

Requirements

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

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

[
  {
    "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:

Copy 
1
2
3
4
5
6
7
8

[
  {
    "objectID": "321432",
    "name": "lemon",
    "categories.lvl0": ["products", "goods"],
    "categories.lvl1": ["products > fruits", "goods > to eat"]
  }
]

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

If there is also a ais-hierarchical-menu on the page, it must follow the same configuration.

Examples

Copy 
1
2
3
4
5
6
7
8

<ais-breadcrumb
  :attributes="[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]"
/>

Props

Parameter Description
attributes
type: string[]
Required

An array of attributes to generate the breadcrumb.

When using an array, take steps to avoid creating infinite loops. When you use an array as a prop, it causes the widget to re-register on every render, and this can sometimes cause these infinite loops.
Copy 
1
2
3
4
5
6
7
8

<ais-breadcrumb
  :attributes="[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]"
/>
root-path
type: string
Optional

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—for example, by setting initial-ui-state.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

<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>
separator
type: string
default: >
Optional

The level separator used in the records.
Copy 
1
2
3
4

<ais-breadcrumb
  [...]
  separator="-"
/>
transform-items
type: function
Optional

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).
Copy 
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

<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>
class-names
type: object
Optional

The CSS classes you can override:

  • 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.
Copy 
1
2
3
4
5
6
7

<ais-breadcrumb
  [...]
  :class-names="{
    'ais-Breadcrumb': 'MyCustomBreadcrumb',
    'ais-Breadcrumb-list': 'MyCustomBreadcrumbList',
  }"
/>

Customize the UI

Parameter Description
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.
Copy 
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

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

The slot to override the root label.
Copy 
1
2
3
4
5
6
7
8
9
10

<ais-breadcrumb
  :attributes="[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]"
>
  <template v-slot:rootLabel>Home page</template>
</ais-breadcrumb>
separator

The slot to override the separator.
Copy 
1
2
3
4
5
6
7
8
9
10

<ais-breadcrumb
  :attributes="[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]"
>
  <template v-slot:separator>→</template>
</ais-breadcrumb>

HTML output

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

If SEO is critical to your search page, your custom HTML markup needs to be parsable:

  • use plain <a> tags with href attributes for search engines bots to follow them,
  • use semantic markup with structured data when relevant, and test it.

Refer to our SEO checklist for building SEO-ready search experiences.

Did you find this page helpful?
Vue InstantSearch v4