ais-breadcrumb

Shows a navigation path based on hierarchical facets.

Signature

<ais-breadcrumb
  :attributes="string[]"
  // Optional parameters
  root-path="string"
  separator="string"
  :transform-items="function"
  :class-names="object"
/>

Import

Component

To ensure optimal bundle sizes, see Optimize build size.

Vue

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

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

Plugin

This imports all widgets, even the ones you don’t use. For more information, see Get started with Vue InstantSearch.

JavaScript

import Vue from "vue";
import InstantSearch from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

Vue.use(InstantSearch);

See this widget in action

Preview this widget and its behavior.

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

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

[
  {
    "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
2. Determine your attributes for faceting from the dashboard or with an API client
3. Display the UI with the hierarchical menu widget.

For more information, see Facet display. 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-manu on the page, it must follow the same configuration.

Examples

Vue

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

Props

attributes · string[] · required

An array of attributes to generate the breadcrumb.

To prevent creating 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.

Vue

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

root-path · 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, for example, by setting initial-ui-state.

Vue

<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 · string · default: " > "

The level separator used in the .

Vue

<ais-breadcrumb
    [...] 
    separator="-" 
/>

transform-items · 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 and parameters from the helper, such as disjunctiveFacetsRefinements.

Vue

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

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.

Vue

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

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

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

Vue

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

Vue

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

HTML output

HTML

<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 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 when relevant.

For more guidance, see the SEO checklist.