API Reference / React InstantSearch Hooks / <SearchBox>

<SearchBox>

A
Signature 
<SearchBox
  // Optional props
  placeholder={string}
  queryHook={(query: string, hook: (value: string) => void) => void}
  onSubmit={React.FormEventHandler<HTMLFormElement>}
  submitIconComponent={React.JSXElementConstructor<IconProps>}
  resetIconComponent={React.JSXElementConstructor<IconProps>}
  loadingIconComponent={React.JSXElementConstructor<IconProps>}
  classNames={Partial<SearchBoxClassNames>}
  ...props={React.ComponentProps<'div'>}
/>
See code examples
See live example

About this widget # A

<SearchBox> is a widget to let users perform a text-based query.

The search box usually is the main entry point to start the search on an InstantSearch page. You typically place it at the top of a search experience so that the user can start searching right away.

You can also create your own UI with useSearchBox().

Examples # A

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

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, SearchBox } from 'react-instantsearch-hooks-web';

const searchClient = algoliasearch('AJ0P3S7DWQ', '90dfaaf5755e694f341fe68f6e41a6d4');

function App() {
  return (
    <InstantSearch indexName="instant_search" searchClient={searchClient}>
      <SearchBox />
    </InstantSearch>
  );
}

Props # A

placeholder #
type: string
Optional

The placeholder text of the input.
Copy 
1

<SearchBox placeholder="Search for products" />
queryHook #
type: (query: string, search: (value: string) => void) => void
Optional

Function called every time the query changes. It takes two parameters:

  • query: The current query.
  • search: The function to trigger the search.

This prop can be useful if you need to:

  • Debounce searches to regulate requests.
  • Programmatically alter the query before sending it to Algolia.

When using this prop, you’re responsible for triggering the search with search(). If you don’t call this function, no search is triggered to Algolia.
Copy 
1
2
3
4
5

<SearchBox
  queryHook={(query, search) => {
    search(query);
  }}
/>
onSubmit #
type: (event: React.FormEvent<HTMLFormElement>) => void
Optional

A callback to run when submitting the form of the search box.
Copy 
1
2
3
4
5

<SearchBox
  onSubmit={(event) => {
    // Code to run when the form submits
  }}
/>
submitIconComponent #
type: React.JSXElementConstructor<IconProps>
Optional

A component to replace the icon in the submit button.

The component receives the passed classNames prop.
Copy 
1
2
3
4
5

<SearchBox
  submitIconComponent={({ classNames }) => (
    <div className={classNames.submitIcon}>Submit</div>
  )}
/>
resetIconComponent #
type: React.JSXElementConstructor<IconProps>
Optional

A component to replace the icon in the reset button.

The component receives the passed classNames prop.
Copy 
1
2
3
4
5

<SearchBox
  resetIconComponent={({ classNames }) => (
    <div className={classNames.resetIcon}>Reset</div>
  )}
/>
loadingIconComponent #
type: React.JSXElementConstructor<IconProps>
Optional

A component to replace the loading icon.

The component receives the passed classNames prop.
Copy 
1
2
3
4
5

<SearchBox
  loadingIconComponent={({ classNames }) => (
    <div className={classNames.loadingIcon}>Loading</div>
  )}
/>
classNames #
type: Partial<SearchBoxClassNames>
Optional

CSS classes to pass to the widget’s elements. This is useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

  • root: The root element of the widget.
  • form: The form element.
  • input: The input element.
  • submit: The submit button.
  • reset: The reset button.
  • loadingIndicator: The loading indicator element.
  • submitIcon: The submit icon.
  • resetIcon: The reset icon.
  • loadingIcon: The loading icon.
Copy 
1
2
3
4
5
6

<SearchBox
  classNames={{
    root: 'MyCustomSearchBox',
    form: 'MyCustomSearchBoxForm MyCustomSearchBoxForm--subclass',
  }}
/>
...props #
type: React.ComponentProps<'div'>
Optional

Any <div> prop to forward to the root element of the widget.
Copy 
1

<SearchBox className="MyCustomSearchBox" title="My custom title" />

Hook# A

React InstantSearch Hooks let you create your own UI for the <SearchBox> widget with useSearchBox(). Hooks provide APIs to access the widget state and interact with InstantSearch.

The useSearchBox() Hook accepts parameters and returns APIs.

See code examples

Usage#

First, create your React component:

import { useSearchBox } from 'react-instantsearch-hooks-web';

function CustomSearchBox(props) {
  const { query, refine, clear, isSearchStalled } = useSearchBox(props);

  return <>{/* Your JSX */}</>;
}

Then, render the widget:

<CustomSearchBox {...props} />

Parameters#

Hooks accept parameters. You can pass them manually, or forward the props from your custom component.

When you provide a function to Hooks, make sure to pass a stable reference with useCallback() to avoid rendering endlessly. Objects and arrays are memoized so you don’t have to stabilize them.

queryHook #
type: (query: string, hook: (value: string) => void) => void
Optional

Function called every time the query changes.

See queryHook for detail.
Copy 
1
2
3
4
5
6

const searchBoxApi = useSearchBox({
  // ...
  queryHook(query, search) {
    search(query);
  },
});

APIs#

Hooks return APIs, such as state and functions. You can use them to build your UI and interact with React InstantSearch.

query #
type: string

The query from the last search.
refine #
type: (value: string) => void

Sets a new query and searches.
clear #
type: () => void

Clears the query and searches.
isSearchStalled #
type: boolean

Whether the search results take more than a certain time to come back from Algolia servers.

This can be configured on <InstantSearch> with the stalledSearchDelay props which defaults to 200 ms.

Example#

Copy 
1
2
3
4
5
6
7
8

import React from 'react';
import { useSearchBox } from 'react-instantsearch-hooks-web';

function CustomSearchBox(props) {
  const { query, refine } = useSearchBox(props);

  return <>{/* Your JSX */}</>;
}
Did you find this page helpful?
React InstantSearch Hooks v6