API Reference / Vue InstantSearch / ais-search-box

ais-search-box

Signature 
<ais-search-box
  // Optional parameters
  placeholder="string"
  submit-title="string"
  reset-title="string"
  :autofocus="boolean"
  :show-loading-indicator="boolean"
  :class-names="object"
/>
Import
Copy 
1
2
3
4
5
6
7
8
9

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

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

1. Follow additional steps in Optimize build size to ensure your code is correctly bundled.
2. This imports all the widgets, even the ones you don’t use. Read the Getting started guide for more information.

See code examples
See live example

About this widget

The ais-search-box widget is used to let the user set a text-based query.

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 the user can start searching right away.

Examples

Copy 
1

<ais-search-box />

Props

placeholder
type: string
default: Search here…
Optional

The input placeholder.
Copy 
1

<ais-search-box placeholder="Search for products..." />
submit-title
type: string
default: search
Optional

The submit button text.
Copy 
1

<ais-search-box submit-title="Submit the query" />
reset-title
type: string
default: clear
Optional

The clear button text.
Copy 
1

<ais-search-box reset-title="Remove the query" />
autofocus
type: boolean
default: false
Optional

Whether to automatically focus on the input when rendered.
Copy 
1

<ais-search-box autofocus />
show-loading-indicator
type: boolean
default: false
Optional

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

<ais-search-box show-loading-indicator />
class-names
type: object
default: {}
Optional

The CSS classes to 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.
Copy 
1
2
3
4
5
6
7

<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.
Copy 
1
2
3
4
5
6
7
8
9
10

<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.
Copy 
1
2
3

<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.
Copy 
1
2
3

<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.
Copy 
1
2
3

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

HTML output

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

<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>
Did you find this page helpful?
Vue InstantSearch v4