Skip to main content
The searchBox widget creates an input field where users can type their search queries. This is typically the main entry point for search interactions.

​
Usage

const searchBox = instantsearch.widgets.searchBox({
  container: '#search-box',
  placeholder: 'Search for products...',
  searchAsYouType: true,
  showReset: true,
  showSubmit: true,
  showLoadingIndicator: true,
});

search.addWidget(searchBox);

​
Examples

instantsearch.widgets.searchBox({
  container: '#search-box',
});

​
With Custom Placeholder

instantsearch.widgets.searchBox({
  container: '#search-box',
  placeholder: 'Search our catalog...',
  autofocus: true,
});

instantsearch.widgets.searchBox({
  container: '#search-box',
  queryHook(query, search) {
    clearTimeout(searchTimeout);
    searchTimeout = setTimeout(() => search(query), 500);
  },
});

​
Search on Enter Only

instantsearch.widgets.searchBox({
  container: '#search-box',
  searchAsYouType: false,
});

​
Options

​
container
string | HTMLElement
required
CSS Selector or HTMLElement to insert the widget.
​
placeholder
string
default:""
The placeholder text shown in the input field.
​
autofocus
boolean
default:"false"
Whether the input should be autofocused when the page loads.
​
searchAsYouType
boolean
default:"true"
If set to false, the search will only be triggered when pressing Enter.
​
ignoreCompositionEvents
boolean
default:"false"
Whether to update the search state during IME composition (useful for Asian languages).
​
showReset
boolean
default:"true"
Whether to show the reset button to clear the query.
​
showSubmit
boolean
default:"true"
Whether to show the submit button.
​
showLoadingIndicator
boolean
default:"true"
Whether to show a loading indicator when the search is stalled.
​
queryHook
function
A function called on each keystroke to transform or debounce the query.
(query: string, search: (query: string) => void) => void
​
templates
object
Templates to customize the widget rendering.
​
cssClasses
object
CSS classes to add to the widget elements.

​
HTML Output

<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">
      <svg class="ais-SearchBox-submitIcon">...</svg>
    </button>
    <button class="ais-SearchBox-reset" type="reset" title="Clear">
      <svg class="ais-SearchBox-resetIcon">...</svg>
    </button>
    <span class="ais-SearchBox-loadingIndicator" hidden>
      <svg class="ais-SearchBox-loadingIcon">...</svg>
    </span>
  </form>
</div>

Build docs developers (and LLMs) love

Get started for freeTalk to us