API Reference / Vue InstantSearch Widgets / ais-breadcrumb

ais-breadcrumb

Widget signature 
<ais-breadcrumb
  :attributes="string[]"
  // Optional parameters
  root-path="string"
  separator="string"
  :transform-items="function"
  :class-names="object"
/>
See code examples
See Live example

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.

All attributes (lvl0, lvl1 in this case) must be declared as attributesForFaceting in your Algolia settings.

Examples

Copy 
1
2
3
4
5
6
7
8

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

Props

attributes
type: string[]
Required

An array of attributes to generate the breadcrumb.
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.
Copy 
1
2
3
4

<ais-breadcrumb
  [...]
  root-path="Audio > Home Audio"
/>
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

Modifies the items being displayed, for example, to filter or sort them. It takes items as argument and expects them back in return.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<template>
  <!-- ... -->
  <ais-breadcrumb
    [...]
    :transform-items="transformItems"
  />
</template>

<script>
  export default {
    methods: {
      transformItems(items) {
        return items.map(item => ({
          ...item,
          label: item.label.toUpperCase(),
        }));
      },
    },
  };
</script>
class-names
type: object
Optional

The CSS classes to 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

default

The slot to override the complete DOM output of the widget.

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

<ais-breadcrumb
  :attributes="[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
    'categories.lvl3',
  ]"
>
  <ul slot-scope="{ items, refine, createURL }">
    <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>
</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',
  ]"
>
  <span slot="rootLabel">Home page</span>
</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',
  ]"
>
  <span slot="separator">→</span>
</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 v3