> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ais-voice-search

> Lets users submit search queries using voice input.

export const SearchQuery = () => <Tooltip tip="The text users enter into a search box. In the Search API, this corresponds to the query parameter. A search query is often used with filters, facets, and other parameters, but these aren't part of the query text itself.">
    search query
  </Tooltip>;

```vue Signature theme={"system"}
<ais-voice-search
  // Optional parameters
  :search-as-you-speak="boolean"
  :button-title="string"
  :disabled-button-title="string"
  :class-names="object"
/>
```

## Import

<Tabs>
  <Tab title="Component">
    To ensure optimal bundle sizes,
    see [Optimize build size](/doc/guides/building-search-ui/going-further/improve-performance/vue#optimize-build-size).

    ```js Vue icon=code theme={"system"}
    import { AisVoiceSearch } from "vue-instantsearch";
    // Use "vue-instantsearch/vue3/es" for Vue 3

    export default {
      components: {
        AisVoiceSearch,
      },
      // ...
    };
    ```
  </Tab>

  <Tab title="Plugin">
    This imports all widgets, even the ones you don't use.
    For more information, see [Get started with Vue InstantSearch](/doc/guides/building-search-ui/getting-started/vue).

    ```js JavaScript icon="code" theme={"system"}
    import Vue from "vue";
    import InstantSearch from "vue-instantsearch";
    // Use "vue-instantsearch/vue3/es" for Vue 3

    Vue.use(InstantSearch);
    ```
  </Tab>
</Tabs>

<Card title="See this widget in action" icon="monitor-play" href="https://instantsearchjs.netlify.app/stories/vue/?selectedKind=ais-voice-search" horizontal>
  Preview this widget and its behavior.
</Card>

## About this widget

The `ais-voice-search` widget lets users perform a voice-based <SearchQuery />.

It uses the [Web Speech API](https://w3c.github.io/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

```vue Vue icon=code theme={"system"}
<ais-voice-search />
```

## Props

<ParamField body="search-as-you-speak" type="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.

  ```vue Vue icon=code theme={"system"}
  <ais-voice-search search-as-you-speak />
  ```
</ParamField>

<ParamField body="button-title" type="string" default="'Search by voice'">
  The `title` attribute on the button.

  ```vue Vue icon=code theme={"system"}
  <ais-voice-search button-title="Voice Search" />
  ```
</ParamField>

<ParamField body="disabled-button-title" type="string" default="'Search by voice (not supported on this browser)'">
  The `title` attribute on the button when it's disabled on unsupported browsers.

  ```vue Vue icon=code theme={"system"}
  <ais-voice-search disabled-button-title="Voice Search Disabled" />
  ```
</ParamField>

<ParamField body="class-names" type="object" default="{}">
  The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/vue#style-your-widgets):

  * `ais-VoiceSearch`. The root element of the widget.
  * `ais-VoiceSearch-button`. The button element.
  * `ais-VoiceSearch-status`. The status element.

  ```vue Vue icon=code theme={"system"}
  <ais-voice-search
    :class-names="{
      'ais-VoiceSearch': 'MyVoiceSearch',
      'ais-VoiceSearch-button': 'MyVoiceSearchButton',
      'ais-VoiceSearch-status': 'MyVoiceSearchStatus'
    }"
  />
  ```
</ParamField>

## Customize the UI

<ParamField body="default">
  The slot to override the complete DOM output of the widget.

  When you implement this slot, none of the other slots will change the output, as the default slot surrounds them.

  **Scope**

  * `isBrowserSupported: boolean`. `true` if user's browser supports voice search.
  * `isListening: boolean`. `true` if listening to user's speech.
  * `toggleListening: () => void`. Starts listening to user's speech, or stops it if already listening.
  * `voiceListeningState: 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](https://w3c.github.io/speech-api/#speechreco-error) for more information.

  ```vue Vue icon=code theme={"system"}
  <ais-voice-search>
    <template v-slot="{
        isBrowserSupported,
        isListening,
        toggleListening,
        voiceListeningState,
    }">
      <button @click="toggleListening">click</button>
      <p>isListening: {{ isListening ? 'true' : 'false' }}</p>
      <p>isBrowserSupported: {{ isBrowserSupported ? 'true' : 'false' }}</p>
      <pre>voiceListeningState: {{
        JSON.stringify(voiceListeningState, null, 2)
      }}</pre>
    </template>
  </ais-voice-search>
  ```
</ParamField>

<ParamField body="buttonText">
  The slot to override the DOM output inside the button.

  **Scope**

  * `isListening: boolean`. `true` if listening to user's speech.
  * `isBrowserSupported: boolean`. `true` if user's browser supports voice search.
  * `status: string`. Current status (`initial`|`askingPermission`|`waiting`|`recognizing`|`finished`|`error`).
  * `errorCode: string | undefined`. An error code (if any).
    Refer to the [spec](https://w3c.github.io/speech-api/#speechreco-error) for more information.
  * `transcript: string`. Currently recognized transcript.
  * `isSpeechFinal: boolean`. `true` if speech recognition is finished.

  ```vue Vue icon=code theme={"system"}
  <ais-voice-search>
    <template v-slot:buttonText="{ isListening }">
      {{ isListening ? 'Stop' : 'Start' }}
    </template>
  </ais-voice-search>
  ```
</ParamField>

<ParamField body="status">
  The slot to override the DOM output of the status.

  **Scope**

  * `isListening: boolean`. `true` if listening to user's speech.
  * `isBrowserSupported: boolean`. `true` if user's browser supports voice search.
  * `status: string`. Current status (`initial`|`askingPermission`|`waiting`|`recognizing`|`finished`|`error`).
  * `errorCode: string | undefined`. An error code (if any).
    Refer to the [spec](https://w3c.github.io/speech-api/#speechreco-error) for more information.
  * `transcript: string`. Currently recognized transcript.
  * `isSpeechFinal: boolean`. `true` if speech recognition is finished.

  ```vue Vue icon=code theme={"system"}
  <ais-voice-search>
    <template v-slot:status="{ status, transcript }">
      <p v-if="status == 'initial'">Press the button to start speaking.</p>
      <p v-else>Searching for {{ transcript }}</p>
    </template>
  </ais-voice-search>
  ```
</ParamField>

## HTML output

```html HTML icon=code-xml theme={"system"}
<div class="ais-VoiceSearch">
  <button class="ais-VoiceSearch-button" type="button" title="Search by voice">
    ...
  </button>
  <div class="ais-VoiceSearch-status">...</div>
</div>
```