UI libraries / Angular InstantSearch / Widgets

ais-breadcrumb

Angular InstantSearch isn’t compatible with Angular’s Ivy view engine. We’re investigating how best to support this. For more information and to vote for Algolia’s support of Angular 16 and beyond, see the GitHub issue Algolia Support for Angular InstantSearch

Signature 
<ais-breadcrumb
  [attributes]="string[]"
  // Optional parameters
  separator="string"
  rootPath="string"
  [autoHideContainer]="boolean"
></ais-breadcrumb>
Import
Copy 
1
2
3
4
5
6
7
8

import { NgAisBreadcrumbModule } from 'angular-instantsearch';

@NgModule({
  imports: [
    NgAisBreadcrumbModule,
  ],
})
export class AppModule {}

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

About this widget

The ais-breadcrumb component 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 is commonly used for websites with lot 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

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

Properties

Parameter Description
attributes
type: string[]
Required

The name of the attributes to generate the menu
Copy 
1
2
3

<ais-breadcrumb
  [attributes]="['categories.lvl0', 'categories.lvl1']"
></ais-breadcrumb>
separator
type: string
default: >
Optional

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

<ais-breadcrumb
  [...]
  separator="-"
></ais-breadcrumb>
rootPath
type: string
Optional

The path to use if the first level is not the root level
Copy 
1

<ais-breadcrumb rootPath="Audio > Home Audio"></ais-breadcrumb>
autoHideContainer
type: boolean
default: true
Optional

Whether to hide the breadcrumb if there’s no item to display
Copy 
1

<ais-breadcrumb [autoHideContainer]="false"></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"> &gt; </span>
      <a class="ais-Breadcrumb-link" href="#">Cameras &amp; Camcorders</a>
    </li>
    <li class="ais-Breadcrumb-item ais-Breadcrumb-item--selected">
      <span class="ais-Breadcrumb-separator"> &gt; </span>
      Digital Cameras
    </li>
  </ul>
</div>

Customize the UI with connectBreadcrumb

If you want to create your own UI of the ais-breadcrumb widget, you can combine the connectBreadcrumb connector with the TypedBaseWidget class.

See code examples

1. Extend the TypedBaseWidget class

First of all, you will need to write some boilerplate code to initialize correctly the TypedBaseWidget class. This happens in the constructor() of your class extending the TypedBaseWidget class.

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

import { Component, Inject, forwardRef, Optional } from '@angular/core';
import { TypedBaseWidget, NgAisInstantSearch, NgAisIndex } from 'angular-instantsearch';

@Component({
  selector: 'app-breadcrumbs',
  template: '<p>It works!</p>'
})
export class Breadcrumbs extends TypedBaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('Breadcrumbs');
  }
}

There are a couple of things happening in this boilerplate:

  • create a Breadcrumbs class extending TypedBaseWidget
  • reference the <ais-instantsearch> parent component instance on the Breadcrumbs widget class
  • set app-breadcrumbs as a selector, so we can use our component as <app-breadcrumbs></app-breadcrumbs>

2. Connect your custom widget

The TypedBaseWidget class has a method called createWidget() which takes two arguments: the connector to use and an object of options (instance options) for this connector. We call this method at ngOnInit. This component now implements OnInit.

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

import { Component, Inject, forwardRef, Optional } from '@angular/core';
import { TypedBaseWidget, NgAisInstantSearch, NgAisIndex } from 'angular-instantsearch';

import connectBreadcrumb, {
  BreadcrumbWidgetDescription,
  BreadcrumbConnectorParams
} from 'instantsearch.js/es/connectors/breadcrumb/connectBreadcrumb';

@Component({
  selector: 'app-breadcrumbs',
  template: '<p>It works!</p>'
})
export class Breadcrumbs extends TypedBaseWidget<BreadcrumbWidgetDescription, BreadcrumbConnectorParams> {
  public state: BreadcrumbWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('Breadcrumbs');
  }
  ngOnInit() {
    this.createWidget(connectBreadcrumb, {
      // instance options
      attributes: ['categories.lvl0', 'categories.lvl1'],
    });
    super.ngOnInit();
  }
}

3. Render from the state

Your component instance has access to a this.state property which holds the rendering options of the widget.

public state: BreadcrumbWidgetDescription['renderState'];
// {
//   items: object[];
//   refine: Function;
//   createURL: Function;
//   widgetParams: object;
// }
Copy 
1
2
3
4
5

<div>
  <a href="#" *ngFor="let item of state.items" (click)="state.refine(item.value)">
    {{ item.name }}
  </a> &gt;
</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.

Rendering options

Parameter Description
items
type: object[]
Required

The items to render, containing the keys:

  • label: the label of the category or subcategory
  • value: the value of breadcrumb item
refine
type: function
default: item.value => undefined
Required

Sets the path of the hierarchical filter and triggers a new search.
createURL
type: function
default: item.value => string
Required

Generates a URL for the next state of a clicked item. The special value null is used for the root item of the breadcrumb and returns an empty array.
widgetParams
type: object

All original widget options forwarded to the render function.

Instance options

Parameter Description
attributes
type: string[]
Required

The attributes to use to generate the hierarchy of the breadcrumb.
rootPath
type: string
Optional

The path to use if the first level is not the root level.
separator
type: string
default: >
Optional

The level separator used in the records.
transformItems
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).

Full example

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
33
34
35
36
37

import { Component, Inject, forwardRef, Optional } from '@angular/core';
import { TypedBaseWidget, NgAisInstantSearch, NgAisIndex } from 'angular-instantsearch';

import connectBreadcrumb, {
  BreadcrumbWidgetDescription,
  BreadcrumbConnectorParams
} from 'instantsearch.js/es/connectors/breadcrumb/connectBreadcrumb';

@Component({
  selector: 'app-breadcrumbs',
  template: `
<div>
  <a href="#" *ngFor="let item of state.items" (click)="state.refine(item.value)">
    {{ item.name }}
  </a> &gt;
</div>
`
})
export class Breadcrumbs extends TypedBaseWidget<BreadcrumbWidgetDescription, BreadcrumbConnectorParams> {
  public state: BreadcrumbWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('Breadcrumbs');
  }
  ngOnInit() {
    this.createWidget(connectBreadcrumb, {
      // instance options
      attributes: ['categories.lvl0', 'categories.lvl1'],
    });
    super.ngOnInit();
  }
}
Did you find this page helpful?
Angular InstantSearch v4