API Reference / Angular InstantSearch Widgets / ais-rating-menu
Apr. 24, 2019

ais-rating-menu

You are reading the documentation for Angular InstantSearch v3, which is in beta. You can find the v2 documentation here.

Widget signature 
<ais-rating-menu
  attribute="string"

  // Optional parameters
  [max]="number"
  andUpLabel="string"
></ais-rating-menu>
See code examples

About this widget #

The ais-rating-menu lets the user refine search results by clicking on stars.

The stars are based on the selected attribute.

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 #

Edit
Copy 
1

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

Props #

attribute #
type: string
Required

The name of the attribute in the record.
Edit
Copy 
1

<ais-rating-menu attribute="rating"></ais-rating-menu>
max #
type: number
default: 5
Optional

The maximum value for the rating.
Edit
Copy 
1
2
3
4

<ais-rating-menu
  // ...
  [max]="3"
></ais-rating-menu>
andUpLabel #
type: string
default: & Up
Optional

Label for the “& Up” message.
Edit
Copy 
1
2
3
4

<ais-rating-menu
  // ...
  andUpLabel="& More"
></ais-rating-menu>

Customize the UI - connectRatingMenu#

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

See code examples

1. Extend the BaseWidget class#

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

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

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

@Component({
  selector: 'app-rating-menu',
  template: '<p>It works!</p>'
})
export class RatingMenu extends BaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('RatingMenu');
  }
}

There are a couple of things happening in this boilerplate:

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

2. Connect your custom widget#

The BaseWidget 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

import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectRatingMenu } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-rating-menu',
  template: '<p>It works!</p>'
})
export class RatingMenu extends BaseWidget {
  public state: {
    // render options
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('RatingMenu');
  }
  ngOnInit() {
    this.createWidget(connectRatingMenu, {
      // instance options
      attribute: 'rating',
    });
    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: {
  items: object[];
  hasNoResults: boolean;
  refine: Function;
  createURL: Function;
}
Copy
1
2
3
4
5
6
7
8
9
10

<ul>
  <li *ngFor="let item of state.items">
    <a href="#" (click)="state.refine(item.value)">
      <span *ngFor="let star of item.stars">
        <span *ngIf="star">★</span>
        <span *ngIf="!star">☆</span>
      </span>
    </a>
  </li>
</ul>

Rendering options #

items #
type: object[]

This list of stars to display, with:

  • count: number: the number of results that match this refinement
  • isRefined: boolean: whether or not the refinement is selected
  • name: string: the name corresponding to the number of stars
  • value: string: the number of stars with a string form
  • stars: boolean[]: the list of stars to generate with:
    • true: a filled star
    • false: an empty star
hasNoResults #
type: boolean

Whether or not the search has results.
refine #
type: function

Selects a rating to filter the results. Takes the value of an item as parameter.
createURL #
type: function

Generates a URL for the next state. Takes the value of an item as parameter.

Instance options #

attribute #
type: string
Required

The name of the attribute in the record.
max #
type: number
default: 5
Optional

The maximum value for the rating.

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

import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectRatingMenu } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-rating-menu',
  template: `
<ul>
  <li *ngFor="let item of state.items">
    <a href="#" (click)="state.refine(item.value)">
      <span *ngFor="let star of item.stars">
        <span *ngIf="star">★</span>
        <span *ngIf="!star">☆</span>
      </span>
    </a>
  </li>
</ul>
`
})
export class RatingMenu extends BaseWidget {
  public state: {
     items: object[];
     hasNoResults: boolean;
     refine: Function;
     createURL: Function;
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('RatingMenu');
  }
  ngOnInit() {
    this.createWidget(connectRatingMenu, {
      // instance options
      attribute: 'rating',
    });
    super.ngOnInit();
  }
}

HTML output#

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
44
45

<div class="ais-RatingMenu">
  <svg xmlns="http://www.w3.org/2000/svg" style="display:none;">
    <symbol id="ais-RatingMenu-starSymbol" viewBox="0 0 24 24">
      <path d="M12 .288l2.833 8.718h9.167l-7.417 5.389 2.833 8.718-7.416-5.388-7.417 5.388 2.833-8.718-7.416-5.389h9.167z"/>
    </symbol>
    <symbol id="ais-RatingMenu-starEmptySymbol" viewBox="0 0 24 24">
      <path d="M12 6.76l1.379 4.246h4.465l-3.612 2.625 1.379 4.246-3.611-2.625-3.612 2.625 1.379-4.246-3.612-2.625h4.465l1.38-4.246zm0-6.472l-2.833 8.718h-9.167l7.416 5.389-2.833 8.718 7.417-5.388 7.416 5.388-2.833-8.718 7.417-5.389h-9.167l-2.833-8.718z"/>
    </symbol>
  </svg>
  <ul class="ais-RatingMenu-list">
    <li class="ais-RatingMenu-item ais-RatingMenu-item--disabled">
      <div class="ais-RatingMenu-link" aria-label="5 & up" disabled>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <span class="ais-RatingMenu-label" aria-hidden="true">& Up</span>
        <span class="ais-RatingMenu-count">2,300</span>
      </div>
    </li>
    <li class="ais-RatingMenu-item ais-RatingMenu-item--selected">
      <a class="ais-RatingMenu-link" aria-label="4 & up" href="#">
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--empty" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starEmptySymbol"></use></svg>
        <span class="ais-RatingMenu-label" aria-hidden="true">& Up</span>
        <span class="ais-RatingMenu-count">2,300</span>
      </a>
    </li>
    <li class="ais-RatingMenu-item">
      <a class="ais-RatingMenu-link" aria-label="3 & up" href="#">
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--full" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starSymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--empty" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starEmptySymbol"></use></svg>
        <svg class="ais-RatingMenu-starIcon ais-RatingMenu-starIcon--empty" aria-hidden="true" width="24" height="24"><use xlink:href="#ais-RatingMenu-starEmptySymbol"></use></svg>
        <span class="ais-RatingMenu-label" aria-hidden="true">& Up</span>
        <span class="ais-RatingMenu-count">1,750</span>
      </a>
    </li>
  </ul>
</div>

Did you find this page helpful?

Angular InstantSearch v3