voiceSearch

Signature

voiceSearch({
  container: string | HTMLElement,
  // Optional parameters
  searchAsYouSpeak?: boolean,
  language?: string,
  additionalQueryParameters?: object,
  templates?: object,
  cssClasses?: object,
});

Import

import { voiceSearch } from "instantsearch.js/es/widgets";

const { voiceSearch } = instantsearch.widgets;
// or directly use instantsearch.widgets.voiceSearch()

See this widget in action

Preview this widget and its behavior.

The voiceSearch widget lets users perform a voice-based . 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

JavaScript

voiceSearch({
  container: "#voicesearch",
});

Options

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

voiceSearch({
  container: "#voicesearch",
});

voiceSearch({
  container: document.querySelector("#voicesearch"),
});

boolean

default:false

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

JavaScript

voiceSearch({
  // ...
  searchAsYouSpeak: true,
});

string

default:"all languages"

The language you want your voiceSearch widget to recognize. The default (all languages) can result in false positives. For example, an English word you pronounce might be recognized as a French word, which can cause irrelevant results. Make sure to give a BCP 47 language tag, like en-US or fr-FR. This language is automatically forwarded to the queryLanguages query parameter.

JavaScript

voiceSearch({
  // ...
  language: "en-US",
});

function

A function that receives the current query and returns the list of search parameters you want to enable for voice search.By default, the following query parameters are set:

ignorePlurals to true
removeStopWords to true
optionalWords to the current query

To disable this behavior, override the return value of additionalQueryParameters.

JavaScript

voiceSearch({
  // ...
  additionalQueryParameters(query) {
    return {
      ignorePlurals: false,
    };
  },
});

object

The templates to use for the widget.

JavaScript

voiceSearch({
  // ...
  templates: {
    // ...
  },
});

object

The CSS classes you can override:

root. The root element of the widget.
button. The button element.
status. The status element.

JavaScript

voiceSearch({
  // ...
  cssClasses: {
    root: "MyCustomVoiceSearch",
    button: [
      "MyCustomVoiceSearchButton",
      "MyCustomVoiceSearchButton--subclass",
    ],
    status: [
      "MyCustomVoiceSearchStatus",
      "MyCustomVoiceSearchStatus--subclass",
    ],
  },
});

Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

string | function

The template used for displaying the button.

voiceSearch({
  // ...
  templates: {
    buttonText(
      {
        isListening,
        status,
        errorCode,
        transcript,
        isSpeechFinal,
        isBrowserSupported,
      },
      { html },
    ) {
      return html`<span>${isListening ? "Stop" : "Start"}</span>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
voiceSearch({
  // ...
  templates: {
    buttonText: "🎙",
  },
});

string | function

The template used for displaying the status.

voiceSearch({
  // ...
  templates: {
    status(
      {
        isListening,
        status,
        errorCode,
        transcript,
        isSpeechFinal,
        isBrowserSupported,
      },
      { html },
    ) {
      const className = isListening ? "listening" : "not-listening";
      return html`
        <div class="${className}">
          <span>${transcript ? transcript : ""}</span>
        </div>
      `;
    },
  },
});

// String-based templates are deprecated, use functions instead.
voiceSearch({
  // ...
  templates: {
    status: `
      <p>status: {{status}}</p>
      <p>errorCode: {{errorCode}}</p>
      <p>isListening: {{isListening}}</p>
      <p>transcript: {{transcript}}</p>
      <p>isSpeechFinal: {{isSpeechFinal}}</p>
      <p>isBrowserSupported: {{isBrowserSupported}}</p>
    `,
  },
});

HTML output

HTML

<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 with `connectVoiceSearch`

If you want to create your own UI of the voiceSearch widget, you can use connectors. To use connectVoiceSearch, you can import it with the declaration relevant to how you installed InstantSearch.js.

import { connectVoiceSearch } from "instantsearch.js/es/connectors";

const { connectVoiceSearch } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectVoiceSearch()

Then it’s a 3-step process:

JavaScript

// 1. Create a render function
const renderVoiceSearch = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customVoiceSearch = connectVoiceSearch(renderVoiceSearch);

// 3. Instantiate
search.addWidgets([
  customVoiceSearch({
    // instance params
  }),
]);

Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

JavaScript

const renderVoiceSearch = (renderOptions, isFirstRender) => {
  const {
    isBrowserSupported,
    isListening,
    toggleListening,
    voiceListeningState,
    widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
};

Render options

boolean

true if user’s browser supports voice search.

JavaScript

const renderVoiceSearch = (renderOptions, isFirstRender) => {
  const { isBrowserSupported } = renderOptions;

  const container = document.querySelector("#voicesearch");

  if (isFirstRender && !isBrowserSupported) {
    const message = document.createElement("p");
    message.innerText = "This browser is not supported.";
    container.appendChild(message);
  }
};

function

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

JavaScript

const renderVoiceSearch = (renderOptions, isFirstRender) => {
  const { toggleListening } = renderOptions;

  const container = document.querySelector("#voicesearch");

  if (isFirstRender) {
    const button = document.createElement("button");
    button.textContent = "Toggle";

    button.addEventListener("click", (event) => {
      toggleListening();
    });

    container.appendChild(button);
  }
};

boolean

true if listening to user’s speech.

JavaScript

const renderVoiceSearch = (renderOptions, isFirstRender) => {
  const { isListening, toggleListening } = renderOptions;

  const container = document.querySelector("#voicesearch");

  if (isFirstRender) {
    const button = document.createElement("button");
    button.textContent = "Toggle";

    button.addEventListener("click", (event) => {
      toggleListening();
    });

    container.appendChild(button);
  }

  container.querySelector("button").textContent = isListening
    ? "Stop"
    : "Start";
};

boolean

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.

JavaScript

const renderVoiceSearch = (renderOptions, isFirstRender) => {
  const { voiceListeningState, toggleListening } = renderOptions;
  const { status, transcript, isSpeechFinal, errorCode } = voiceListeningState;

  const container = document.querySelector("#voicesearch");

  if (isFirstRender) {
    const state = document.createElement("div");
    state.innerHTML = `
      <p>status : <span class="status"></span></p>
      <p>transcript : <span class="transcript"></span></p>
      <p>isSpeechFinal : <span class="is-speech-final"></span></p>
      <p>errorCode : <span class="error-code"></span></p>
    `;
    container.appendChild(state);

    const button = document.createElement("button");
    button.textContent = "Toggle";
    button.addEventListener("click", (event) => {
      toggleListening();
    });
    container.appendChild(button);
  }
  container.querySelector(".status").innerText = status;
  container.querySelector(".transcript").innerText = transcript;
  container.querySelector(".is-speech-final").innerText = isSpeechFinal;
  container.querySelector(".error-code").innerText = errorCode || "";
};

All original widget options forwarded to the render function.

JavaScript

const renderVoiceSearch = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = "...";
};

const customVoiceSearch = connectVoiceSearch(renderVoiceSearch);

search.addWidgets([
  customVoiceSearch({
    container: document.querySelector("#voicesearch"),
  }),
]);

First, create your custom widgets using a rendering function. Then, instantiate them with parameters. There are two kinds of parameters you can pass:

Instance parameters. Predefined options that configure Algolia’s behavior.
Custom parameters. Parameters you define to make the widget reusable and adaptable.

Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.

JavaScript

const customVoiceSearch = connectVoiceSearch(
  renderVoiceSearch
);

search.addWidgets([
  customVoiceSearch({
    // Optional parameters
    searchAsYouSpeak?: boolean,
  })
]);

Instance options

boolean

default:false

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

JavaScript

customVoiceSearch({
  searchAsYouSpeak: true,
});

string

default:"all languages"

JavaScript

customVoiceSearch({
  // ...
  language: "en-US",
});

function

A function that receives the current query and returns the list of search parameters you want to enable for voice search.By default, the following query parameters are set:

ignorePlurals to true
removeStopWords to true
optionalWords to the current query

To disable this behavior, override the return value of additionalQueryParameters.

JavaScript

customVoiceSearch({
  // ...
  additionalQueryParameters(query) {
    return {
      ignorePlurals: false,
    };
  },
});

Full example

<div id="voicesearch"></div>

// Create a render function
const renderVoiceSearch = (renderOptions, isFirstRender) => {
  const { isListening, toggleListening, voiceListeningState } = renderOptions;

  const container = document.querySelector("#voicesearch");

  if (isFirstRender) {
    const button = document.createElement("button");
    button.addEventListener("click", (event) => {
      toggleListening();
    });
    container.appendChild(button);

    const state = document.createElement("pre");
    container.appendChild(state);
  }

  container.querySelector("button").textContent = isListening
    ? "Stop"
    : "Start";

  container.querySelector("pre").textContent = JSON.stringify(
    voiceListeningState,
    null,
    2,
  );
};

// create custom widget
const customVoiceSearch = connectVoiceSearch(renderVoiceSearch);

// instantiate custom widget
search.addWidgets([
  customVoiceSearch({
    container: document.querySelector("#voicesearch"),
  }),
]);

InstantSearch.js

Import

See this widget in action

About this widget

Examples

Options

Templates

HTML output

Customize the UI with `connectVoiceSearch`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example

​Import

See this widget in action

​About this widget

​Examples

​Options

​Templates

​HTML output

​Customize the UI with connectVoiceSearch

​Create a render function

​Render options

​Create and instantiate the custom widget

​Instance options

​Full example

Import

About this widget

Examples

Options

Templates

HTML output

Customize the UI with `connectVoiceSearch`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example