API Reference / Angular InstantSearch / ais-menu

ais-menu

A
Signature 
<ais-menu
  attribute="string"

  // Optional parameters
  [limit]="number"
  [showMore]="boolean"
  [showMoreLimit]="number"
  showMoreLabel="string"
  showLessLabel="string"
  [sortBy]="string[]|function"
  [autoHideContainer]="boolean"
  [transformItems]="function"
></ais-configure>
See code examples

About this widget # A

The ais-menu allows a user to select a single value to refine from a list.

Requirements#

The attributes passed to the attributes prop must be declared as Attributes for faceting on the Algolia dashboard or configured as attributesForFaceting with the Algolia API.

Examples # A

Copy 
1

<ais-menu attribute="brand"></ais-menu>

Props # A

attribute #
type: string
Required

The name of the attribute in the record.
Copy 
1

<ais-menu attribute="brand"></ais-menu>
limit #
type: number
default: 10
Optional

How many facet values to retrieve. When you enable the showMore feature, this is the number of facet values to display before clicking the “Show more” button.
Copy 
1
2
3
4

<ais-menu
  // ...
  [limit]="20"
></ais-menu>
showMore #
type: boolean
default: false
Optional

Controls the display of the show more button.
Copy 
1
2
3
4

<ais-menu
  // ...
  [showMore]="true"
></ais-menu>
showMoreLimit #
type: number
Optional

Amount of items to show if showing more.
Copy 
1
2
3
4
5

<ais-menu
  // ...
  [showMore]="true"
  [showMoreLimit]="20"
></ais-menu>
showMoreLabel #
type: string
default: Show more
Optional

Label of the “Show more” button.
Copy 
1
2
3
4
5

<ais-menu
  // ...
  [showMore]="true"
  showMoreLabel="See more"
></ais-menu>
showLessLabel #
type: string
default: Show less
Optional

Label of the show less button.
Copy 
1
2
3
4
5

<ais-menu
  // ...
  [showMore]="true"
  showLessLabel="See less"
></ais-menu>
sortBy #
type: string[]|Function
default: ["name:asc"]
Optional

How to sort refinements. Must be one or more of the following strings:

  • "count" (same as "count:desc")
  • "count:asc"
  • "count:desc"
  • "name" (same as "name:asc")
  • "name:asc"
  • "name:desc"
  • "isRefined" (same as "isRefined:asc")
  • "isRefined:asc"
  • "isRefined:desc"

It’s also possible to give a function, which receives items two by two, like JavaScript’s Array.sort.
Copy 
1
2
3
4

<ais-menu
  // ...
  [sortBy]="['name:desc']"
></ais-menu>
autoHideContainer #
type: boolean
Optional

Hides the menu if there’s no item to display.
Copy 
1
2
3
4

<ais-menu
  // ...
  [autoHideContainer]="true"
></ais-menu>
transformItems #
type: function
default: items => items
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

@Component({
  template: `
    <ais-menu
      // ...
      [transformItems]="transformItems"
    ></ais-menu>
  `,
})
export class AppComponent {
  transformItems(items) {
    return items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }));
  },

  /* or, combined with results */
  transformItems(items, { results }) {
    return items.map(item => ({
      ...item,
      label: item.isRefined
        ? `${item.label} (${results.nbPages} pages)`
        : item.label,
    }));
  },
}

HTML output# A

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

<div class="ais-Menu">
  <div class="ais-Menu-searchBox">
    <!-- SearchBox widget here -->
  </div>
  <ul class="ais-Menu-list">
    <li class="ais-Menu-item ais-Menu-item--selected">
      <a class="ais-Menu-link" href="#">
        <span class="ais-Menu-label">Appliances</span>
        <span class="ais-Menu-count">4,306</span>
      </a>
    </li>
    <li class="ais-Menu-item">
      <a class="ais-Menu-link" href="#">
        <span class="ais-Menu-label">Audio</span>
        <span class="ais-Menu-count">1,570</span>
      </a>
    </li>
  </ul>
  <button class="ais-Menu-showMore">Show more</button>
</div>

Customize the UI with connectMenu# A

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

This connector is also used to build other widgets: MenuSelect

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-menu',
  template: '<p>It works!</p>'
})
export class Menu extends TypedBaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('Menu');
  }
}

There are a couple of things happening in this boilerplate:

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

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 connectMenu, {
  MenuWidgetDescription,
  MenuConnectorParams
} from 'instantsearch.js/es/connectors/menu/connectMenu';

@Component({
  selector: 'app-menu',
  template: '<p>It works!</p>'
})
export class Menu extends TypedBaseWidget<MenuWidgetDescription, MenuConnectorParams> {
  public state: MenuWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('Menu');
  }
  ngOnInit() {
    this.createWidget(connectMenu, {
      // instance options
      attribute: 'brand',
    });
    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: MenuWidgetDescription['renderState'];
// {
//   items: object[];
//   refine: Function;
//   createURL: Function;
//   isShowingMore: boolean;
//   canToggleShowMore: boolean;
//   toggleShowMore: Function;
//   widgetParams: object;
// }
Copy 
1
2
3
4
5
6
7
8
9
10
11

<select
  class="menu-select"
  (change)="state.refine($event.target.value)"
>
  <option
    *ngFor="let item of state.items"
    [value]="item.value"
    [selected]="item.isRefined">
    {{ item.label }}
  </option>
</select>

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 #

items #
type: object[]

The elements that can be refined for the current search results. With each item:

  • value: string: the value of the menu item
  • label: string: the label of the menu item
  • count: number: the number of results matched after a refinement is applied
  • isRefined: boolean: whether the refinement is applied
refine #
type: function

Toggles a refinement.
createURL #
type: function
default: (item.value) => string

Generates a URL for the corresponding search state.
isShowingMore #
type: boolean

Whether the menu is displaying all the menu items.
canToggleShowMore #
type: boolean

Whether the “Show more” button can be activated (enough items to display more and not already displaying more than the limit).
toggleShowMore #
type: function

Toggles the number of displayed values between limit and showMoreLimit.
widgetParams #
type: object

All original widget options forwarded to the render function.

Instance options #

attribute #
type: string
Required

The name of the attribute for faceting.
limit #
type: number
default: 10
Optional

How many facet values to retrieve. When you enable the
showMoreLimit #
type: number
default: 10
Optional

How many facet values to retrieve when showing more.
sortBy #
type: string[]|function
default: ["isRefined", "name:asc"]
Optional

How to sort refinements. Must be one or more of the following strings:

  • "count:asc"
  • "count:desc"
  • "name:asc"
  • "name:desc"
  • "isRefined"

It’s also possible to give a function, which receives items two by two, like JavaScript’s Array.sort.
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
38
39
40
41
42
43

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

import connectMenu, {
  MenuWidgetDescription,
  MenuConnectorParams
} from 'instantsearch.js/es/connectors/menu/connectMenu';

@Component({
  selector: 'app-menu',
  template: `
<select
  class="menu-select"
  (change)="state.refine($event.target.value)"
>
  <option
    *ngFor="let item of state.items"
    [value]="item.value"
    [selected]="item.isRefined">
    {{ item.label }}
  </option>
</select>
`
})
export class Menu extends TypedBaseWidget<MenuWidgetDescription, MenuConnectorParams> {
  public state: MenuWidgetDescription['renderState']; // Rendering options
  constructor(
    @Inject(forwardRef(() => NgAisIndex))
    @Optional()
    public parentIndex: NgAisIndex,
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchInstance: NgAisInstantSearch
  ) {
    super('Menu');
  }
  ngOnInit() {
    this.createWidget(connectMenu, {
      // instance options
      attribute: 'brand',
    });
    super.ngOnInit();
  }
}
Did you find this page helpful?
Angular InstantSearch v4