API Reference / Angular InstantSearch Widgets / ais-voice-search
Aug. 23, 2019

ais-voice-search

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

Widget signature
<ais-voice-search
  // Optional parameters
  [searchAsYouSpeak]="boolean"
></ais-voice-search>

About this widget

The ais-voice-search widget lets the user perform a voice-based query.

It uses the Web Speech API, which only Chrome (from version 25) has implemented so far. This means the voiceSearch widget only works on desktop Chrome and Android Chrome. It doesn’t work on iOS Chrome, which uses the iOS WebKit.

Examples

1
<ais-voice-search></ais-voice-search>

Props

searchAsYouSpeak
type: boolean
default: false
Optional

Whether or not to trigger the search as you speak. If false, search is triggered only after speech is finished. If true, search is triggered whenever the engine delivers an interim transcript.

1
2
3
<ais-voice-search
  [searchAsYouSpeak]="true"
></ais-voice-search>
buttonTitle
type: string
default: 'Search by voice'
Optional

The title attribute on the button

1
2
3
<ais-voice-search
  buttonTitle="Voice Search"
></ais-voice-search>
disabledButtonTitle
type: string
default: 'Search by voice (not supported on this browser)'
Optional

The title attribute on the button when it’s disabled on unsupported browsers

1
2
3
<ais-voice-search
  disabledButtonTitle="Voice Search Disabled"
></ais-voice-search>

HTML output

1
2
3
4
5
6
7
8
<div class="ais-VoiceSearch">
  <button class="ais-VoiceSearch-button" type="button" title="Search by voice">
    ...
  </button>
  <div class="ais-VoiceSearch-status">
    ...
  </div>
</div>

Customize the UI - connectVoiceSearch

If you want to create your own UI of the ais-voice-search widget, you can combine the connectVoiceSearch connector with the BaseWidget class.

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.

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-voice-search',
  template: '<p>It works!</p>'
})
export class VoiceSearch extends BaseWidget {
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('VoiceSearch');
  }
}

There are a couple of things happening in this boilerplate:

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

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.

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
import { Component, Inject, forwardRef } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectVoiceSearch } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-voice-search',
  template: '<p>It works!</p>'
})
export class VoiceSearch extends BaseWidget {
  public state: {
    // render options
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('VoiceSearch');
  }
  ngOnInit() {
    this.createWidget(connectVoiceSearch, {
      // instance options
    });
    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: {
  isBrowserSupported: boolean;
  isListening: boolean;
  toggleListening: Function;
  voiceListeningState: object;
  widgetParams: object;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
<div>
  <button
    type="button"
    (click)="this.state.toggleListening()"
  >
    {{ state.isListening ? 'Stop' : 'Start' }}
  </button>
  <p>isBrowserSupported: {{ this.state.isBrowserSupported }}</p>
  <p>isListening: {{ this.state.isListening }}</p>
  <pre>
    {{ this.state.voiceListeningState | json }}
  </pre>
</div>

Rendering options

isBrowserSupported
type: boolean

true if user’s browser supports voice search.

isListening
type: boolean

true if listening to user’s speech.

toggleListening
type: function

Starts listening to user’s speech, or stops it if already listening.

voiceListeningState
type: object

An object containing the following states regarding speech recognition:

  • status: string: current status (initial|askingPermission| waiting|recognizing|finished|error).
  • transcript: string: currently recognized transcript.
  • isSpeechFinal: boolean: true if speech recognition is finished.
  • errorCode: string|undefined: an error code (if any). Refer to the spec for more information.
widgetParams
type: object

All original widget options forwarded to the render function.

Instance options

searchAsYouSpeak
type: boolean
Optional

Whether or not to trigger the search as you speak. If false, search is triggered only after speech is finished. If true, search is triggered whenever the engine delivers an interim transcript.

Full example

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 } from '@angular/core';
import { BaseWidget, NgAisInstantSearch } from 'angular-instantsearch';
import { connectVoiceSearch } from 'instantsearch.js/es/connectors';

@Component({
  selector: 'app-voice-search',
  template: `
<div>
  <button
    type="button"
    (click)="this.state.toggleListening()"
  >
    {{ state.isListening ? 'Stop' : 'Start' }}
  </button>
  <p>isBrowserSupported: {{ this.state.isBrowserSupported }}</p>
  <p>isListening: {{ this.state.isListening }}</p>
  <pre>
    {{ this.state.voiceListeningState | json }}
  </pre>
</div>
`
})
export class VoiceSearch extends BaseWidget {
  public state: {
     isBrowserSupported: boolean;
     isListening: boolean;
     toggleListening: Function;
     voiceListeningState: object;
     widgetParams: object;
  };
  constructor(
    @Inject(forwardRef(() => NgAisInstantSearch))
    public instantSearchParent
  ) {
    super('VoiceSearch');
  }
  ngOnInit() {
    this.createWidget(connectVoiceSearch, {
      // instance options
    });
    super.ngOnInit();
  }
}

Did you find this page helpful?