API Reference / React InstantSearch Widgets / SearchBox
Feb. 15, 2019

SearchBox

Widget 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

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 is usually placed at the top of a search experience, so that the user can start searching right away.

Examples

Copy
jsx
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
jsx
1

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

Whether the search box must be focused on render.
Copy
jsx
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
jsx
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
jsx
1

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

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

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

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

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

Changes the apparence of the default loading indicator (spinning circle).
Copy
jsx
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
jsx
1

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

Intercepts submit event sent from the SearchBox form container.
Copy
jsx
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
jsx
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
jsx
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
jsx
1
2
3
4
5
6
7

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

Customize the UI

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.

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
jsx
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
jsx
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
jsx
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
jsx
1

<CustomSearchBox defaultRefinement="iphone" />

Full example

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

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)}
    />
    {isSearchStalled ? 'My search is stalled' : ''}
  </form>
);

const CustomSearchBox = connectSearchBox(SearchBox);

Did you find this page helpful?

React