API Reference / React InstantSearch / SearchBox

SearchBox

Signature 
<SearchBox
  // Optional parameters
  defaultRefinement={string}
  autoFocus={boolean}
  searchAsYouType={boolean}
  showLoadingIndicator={boolean}
  submit={React.Node}
  reset={React.Node}
  loadingIndicator={React.Node}
  focusShortcuts={string[]}
  onSubmit={function}
  onReset={function}
  on*={function}
  translations={object}
/>
See code examples
See live example

About this widget

We released React InstantSearch Hooks, a new InstantSearch library for React. We recommend using React InstantSearch Hooks in new projects or upgrading from React InstantSearch.

The SearchBox widget is used to let the user perform 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
2
3

import { SearchBox } from 'react-instantsearch-dom';

<SearchBox />

Props

defaultRefinement
type: string
Optional

Provides a default refinement value when component is mounted.
Copy 
1

<SearchBox defaultRefinement="iphone" />
autoFocus
type: boolean
default: false
Optional

Whether the search box must be focused on render.
Copy 
1

<SearchBox autoFocus />
searchAsYouType
type: boolean
default: true
Optional

Whether a search needs to be made on every change to the query. If false, new searches are only triggered by clicking the search button or by pressing the Enter key while the search box is focused.
Copy 
1

<SearchBox searchAsYouType={false} />
showLoadingIndicator
type: boolean
default: false
Optional

Displays that the search is loading. This only happens after a certain amount of time to avoid a blinking effect. The timer can be configured with the stalledSearchDelay prop on the InstantSearch component.
Copy 
1

<SearchBox showLoadingIndicator />
submit
type: React.Node
Optional

Changes the appearance of the default submit button (magnifying glass).
Copy 
1
2
3

<SearchBox
  submit={<img src="/submit.png" alt=""/>}
/>
reset
type: React.Node
Optional

Changes the appearance of the default reset button (cross).
Copy 
1
2
3

<SearchBox
  reset={<img src="/reset.png" alt=""/>}
/>
loadingIndicator
type: React.Node
Optional

Changes the appearance of the default loading indicator (spinning circle).
Copy 
1
2
3
4
5

<SearchBox
  loadingIndicator={
    <img src="/loadingIndicator.png" alt="" />
  }
/>
focusShortcuts
type: string[]
default: ['s','/']
Optional

A list of keyboard shortcuts that focus the search box. Accepts key names and key codes.
Copy 
1

<SearchBox focusShortcuts={['s']} />
onSubmit
type: function
Optional

Intercepts submit event sent from the SearchBox form container.
Copy 
1
2
3
4
5
6

<SearchBox
  onSubmit={event => {
    event.preventDefault();
    console.log(event.currentTarget);
  }}
/>
onReset
type: function
Optional

Intercepts reset event sent from the SearchBox form container.
Copy 
1
2
3
4
5

<SearchBox
  onReset={event => {
    console.log(event.currentTarget);
  }}
/>
on*
type: function
Optional

Listens to any event sent from the SearchBox itself.
Copy 
1
2
3
4
5

<SearchBox
  onClick={event => {
    console.log(event.currentTarget);
  }}
/>
translations
type: object
Optional

A mapping of keys to translation values.

  • submitTitle: the alternative text of the submit icon.
  • resetTitle: the alternative text of the reset button icon.
  • placeholder: the label of the input placeholder.
Copy 
1
2
3
4
5
6
7

<SearchBox
  translations={{
    submitTitle: 'Submit your search query.',
    resetTitle: 'Clear your search query.',
    placeholder: 'Search here...',
  }}
/>

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>

Customize the UI with connectSearchBox

If you want to create your own UI of the SearchBox widget or use another UI library, you can use connectors.

Connectors are higher-order components. They encapsulate the logic for a specific kind of widget and they provide a way to interact with the InstantSearch context.

They have an outer component API that we call exposed props, and they provide some other props to the wrapped components which are called the provided props.

This connector is also used to build other widgets: VoiceSearch

It’s a 3-step process:

// 1. Create a React component
const SearchBox = () => {
  // return the DOM output
};

// 2. Connect the component using the connector
const CustomSearchBox = connectSearchBox(SearchBox);

// 3. Use your connected widget
<CustomSearchBox />

See code examples

Create a React component

const SearchBox = ({
  string currentRefinement,
  boolean isSearchStalled,
  function refine,
}) => {
  // return the DOM output
};

Provided Props

currentRefinement
type: string

The current query.
Copy 
1
2
3
4
5
6
7

const SearchBox = ({ currentRefinement, refine }) => (
  <input
    type="search"
    value={currentRefinement}
    onChange={event => refine(event.currentTarget.value)}
  />
);
isSearchStalled
type: boolean

Whether InstantSearch has detected that searches are stalled.
Copy 
1
2
3
4
5
6
7
8
9
10

const SearchBox = ({ isSearchStalled }) => (
  <div>
    <input
      type="search"
      value={currentRefinement}
      onChange={event => refine(event.currentTarget.value)}
    />
    {isSearchStalled ? 'My search is stalled' : ''}
  </div>
);
refine
type: function

Changes the current query.
Copy 
1
2
3
4
5
6
7

const SearchBox = ({ currentRefinement, refine }) => (
  <input
    type="search"
    value={currentRefinement}
    onChange={event => refine(event.currentTarget.value)}
  />
);

Create and instantiate your connected widget

const CustomSearchBox = connectSearchBox(SearchBox);

<CustomSearchBox
  // optional parameters
  defaultRefinement={string}
/>

Exposed Props

defaultRefinement
type: string
Optional

Provides a default value for the query.
Copy 
1

<CustomSearchBox defaultRefinement="iphone" />

Full example

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

import { connectSearchBox } from 'react-instantsearch-dom';

const SearchBox = ({ currentRefinement, isSearchStalled, refine }) => (
  <form noValidate action="" role="search">
    <input
      type="search"
      value={currentRefinement}
      onChange={event => refine(event.currentTarget.value)}
    />
    <button onClick={() => refine('')}>Reset query</button>
    {isSearchStalled ? 'My search is stalled' : ''}
  </form>
);

const CustomSearchBox = connectSearchBox(SearchBox);
Did you find this page helpful?
React InstantSearch v6