ais-search-box

Lets users perform a search using text input.

Signature

<ais-search-box
  // Optional parameters
  placeholder="string"
  submit-title="string"
  reset-title="string"
  :autofocus="boolean"
  :ignore-composition-events="boolean"
  :show-loading-indicator="boolean"
  :class-names="object"
/>

Import

Component

To ensure optimal bundle sizes, see Optimize build size.

Vue

import { AisSearchBox } from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

export default {
  components: {
    AisSearchBox,
  },
  // ...
};

Plugin

This imports all widgets, even the ones you don’t use. For more information, see Get started with Vue InstantSearch.

JavaScript

import Vue from "vue";
import InstantSearch from "vue-instantsearch";
// Use "vue-instantsearch/vue3/es" for Vue 3

Vue.use(InstantSearch);

See this widget in action

Preview this widget and its behavior.

About this widget

The ais-search-box widget is used to let users set a text-based .

This usually is the main entry point to start the search in an InstantSearch context. It’s usually placed at the top of a search experience, so that users can start searching right away.

Examples

Vue

<ais-search-box />

Props

placeholder · string · default: "Search here…"

The input placeholder.

Vue

<ais-search-box placeholder="Search for products..." />

submit-title · string · default: "search"

The submit button text.

Vue

<ais-search-box submit-title="Submit the query" />

reset-title · string · default: "clear"

The clear button text.

Vue

<ais-search-box reset-title="Remove the query" />

autofocus · boolean · default: false

Whether to automatically focus on the input when rendered.

Vue

<ais-search-box autofocus />

ignore-composition-events · boolean · default: false · since: v4.13.6

Whether to update the search state in the middle of a composition session. This is useful when users need to search using non-latin characters.

Vue

<ais-search-box ignore-composition-events />

show-loading-indicator · boolean · default: false

Whether to show the loading indicator (replaces the submit button if the search is stalled).

Vue

<ais-search-box show-loading-indicator />

class-names · object · default: "{}"

The CSS classes you can override:

• ais-SearchBox. The root element of the widget.
• ais-SearchBox-form. The form element.
• ais-SearchBox-input. The input element.
• ais-SearchBox-submit. The submit button element.
• ais-SearchBox-submitIcon. Magnifier icon used with The search input.
• ais-SearchBox-reset. The reset button element.
• ais-SearchBox-resetIcon. The reset button icon.
• ais-SearchBox-loadingIndicator. The loading indicator element.
• ais-SearchBox-loadingIcon. The loading indicator icon.

Vue

<ais-search-box
  :class-names="{
    'ais-SearchBox': 'MySearchBox',
    'ais-SearchBox-form': 'MySearchBoxForm',
    // ...
  }"
/>

Customize the UI

default

The slot to override the complete DOM output of the widget.

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

Scope

• currentRefinement: string: the current query used for the search.
• isSearchStalled: boolean: whether InstantSearch has detected that searches are stalled.
• refine: (string) => void: the function to change the query.

Vue

<ais-search-box>
  <template v-slot="{ currentRefinement, isSearchStalled, refine }">
    <input
      type="search"
      :value="currentRefinement"
      @input="refine($event.currentTarget.value)"
    >
    <span :hidden="!isSearchStalled">Loading...</span>
  </template>
</ais-search-box>

submit-icon

The slot to override the DOM output of the submit icon.

Scope

No props are provided.

Vue

<ais-search-box>
  <template v-slot:submit-icon>🔎</template>
</ais-search-box>

reset-icon

The slot to override the DOM output of the reset icon.

Scope

No props are provided.

Vue

<ais-search-box>
  <template v-slot:reset-icon>🚫</template>
</ais-search-box>

loading-indicator

The slot to override the DOM output of the loading indicator.

Scope

No props are provided.

Vue

<ais-search-box>
  <template v-slot:loading-indicator>⏳</template>
</ais-search-box>

HTML output

HTML

<div class="ais-SearchBox">
  <form class="ais-SearchBox-form" novalidate>
    <input
      class="ais-SearchBox-input"
      autocomplete="off"
      autocorrect="off"
      autocapitalize="off"
      placeholder="Search for products"
      spellcheck="false"
      maxlength="512"
      type="search"
      value=""
    />
    <button
      class="ais-SearchBox-submit"
      type="submit"
      title="Submit the search query."
    >
      <svg
        class="ais-SearchBox-submitIcon"
        xmlns="http://www.w3.org/2000/svg"
        width="10"
        height="10"
        viewBox="0 0 40 40"
      >
        ...
      </svg>
    </button>
    <button
      class="ais-SearchBox-reset"
      type="reset"
      title="Clear the search query."
      hidden
    >
      <svg
        class="ais-SearchBox-resetIcon"
        xmlns="http://www.w3.org/2000/svg"
        viewBox="0 0 20 20"
        width="10"
        height="10"
      >
        ...
      </svg>
    </button>
    <span class="ais-SearchBox-loadingIndicator" hidden>
      <svg
        width="16"
        height="16"
        viewBox="0 0 38 38"
        xmlns="http://www.w3.org/2000/svg"
        stroke="#444"
        class="ais-SearchBox-loadingIcon"
      >
        ...
      </svg>
    </span>
  </form>
</div>