SearchBox

Lets users perform a search using text input.

This is the React InstantSearch v7 documentation. If you’re upgrading from v6, see the upgrade guide. If you were using React InstantSearch Hooks, this v7 documentation applies—just check for necessary changes. To continue using v6, you can find the archived documentation.

Signature

<SearchBox
  // Optional props
  placeholder={string}
  queryHook={function}
  ignoreCompositionEvents={boolean}
  searchAsYouType={boolean}
  aiMode={boolean}
  autoFocus={boolean}
  onSubmit={function}
  submitIconComponent={() => JSX.Element}
  resetIconComponent={() => JSX.Element}
  loadingIconComponent={() => JSX.Element}
  aiModeIconComponent={() => JSX.Element}
  classNames={object}
  translations={object}
  ...props={ComponentProps<'div'>}
/>

Import

JavaScript

import { SearchBox } from "react-instantsearch";

See this widget in action

Preview this widget and its behavior.

About this widget

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

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

You can also create your own UI with useSearchBox.

Examples

JavaScript

import React from "react";
import { liteClient as algoliasearch } from "algoliasearch/lite";
import { InstantSearch, SearchBox } from "react-instantsearch";

const searchClient = algoliasearch("YourApplicationID", "YourSearchOnlyAPIKey");

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

Props

placeholder · string

The placeholder text of the input.

JavaScript

<SearchBox placeholder="Search for products" />;

queryHook · (query: string, search: (value: string) => void) => void

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.

JavaScript

const queryHook = (query, search) => {
  search(query);
};

function Search() {
  return <SearchBox queryHook={queryHook} />;
}

import type { SearchBoxProps } from "react-instantsearch";

const queryHook: SearchBoxProps["queryHook"] = (query, search) => {
  search(query);
};

function Search() {
  return <SearchBox queryHook={queryHook} />;
}

ignoreCompositionEvents · boolean · default: false · since: v7.5.4

Whether to update the search state in the middle of a composition session. This is useful when users need to search using non-latin characters.

JavaScript

<SearchBox ignoreCompositionEvents />;

searchAsYouType · boolean · default: true

Whether to make a search 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 focusing the search box.

JavaScript

<SearchBox searchAsYouType={false} />;

aiMode · boolean · default: false

Whether to show an AI Mode button in the search box. When users click this button, it opens the Chat widget and sends the current query.

To use this prop, add a <Chat> widget on the same index. For an end-to-end walkthrough, see Build an AI-powered search experience.

JavaScript

<SearchBox aiMode />;

autoFocus · boolean · default: false

Whether the input should be autofocused.

JavaScript

<SearchBox autoFocus />;

onSubmit · (event: React.FormEvent<HTMLFormElement>) => void

A callback to run when submitting the form of the search box.

JavaScript

<SearchBox
  onSubmit={(event) => {
    // Code to run when the form submits
  }}
/>;

submitIconComponent · (props: IconProps) => JSX.Element

A component to replace the icon in the submit button.

The component receives the passed classNames prop.

JavaScript

<SearchBox
  submitIconComponent={({ classNames }) => (
    <div className={classNames.submitIcon}>Submit</div>
  )}
/>;

resetIconComponent · (props: IconProps) => JSX.Element

A component to replace the icon in the reset button.

The component receives the passed classNames prop.

JavaScript

<SearchBox
  resetIconComponent={({ classNames }) => (
    <div className={classNames.resetIcon}>Reset</div>
  )}
/>;

loadingIconComponent · (props: IconProps) => JSX.Element

A component to replace the loading icon.

The component receives the passed classNames prop.

JavaScript

<SearchBox
  loadingIconComponent={({ classNames }) => (
    <div className={classNames.loadingIcon}>Loading</div>
  )}
/>;

aiModeIconComponent · (props: IconProps) => JSX.Element

A component to replace the icon in the AI Mode button.

The component receives the passed classNames prop.

JavaScript

<SearchBox
  aiMode
  aiModeIconComponent={({ classNames }) => (
    <div className={classNames.aiModeIcon}>AI</div>
  )}
/>;

classNames · Partial<SearchBoxClassNames>

The CSS classes you can override and pass to the widget’s elements. It’s 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.
• aiModeButton. The AI mode button.
• aiModeIcon. The AI mode icon.
• aiModeLabel. The AI mode label.

JavaScript

<SearchBox
  classNames={{
    root: "MyCustomSearchBox",
    form: "MyCustomSearchBoxForm MyCustomSearchBoxForm--subclass",
  }}
/>;

translations · Partial<SearchBoxTranslations>

A dictionary of translations to customize the UI text and support internationalization.

• submitButtonTitle. The submit button’s title.
• resetButtonTitle. The reset button’s title.
• aiModeButtonTitle. The AI mode button’s title.

JavaScript

<SearchBox
  translations={{
    submitButtonTitle: "Search",
    resetButtonTitle: "Reset",
    aiModeButtonTitle: "Ask AI",
  }}
/>;

...props · React.ComponentProps<'div'>

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

JavaScript

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

Hook

React InstantSearch 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. It must be used inside the <InstantSearch> component.

Usage

First, create your React component:

JavaScript

import { useSearchBox } from "react-instantsearch";

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

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

Then, render the widget:

JavaScript

<CustomSearchBox {...props} />;

Parameters

Hooks accept parameters. You can either pass them manually or forward props from a custom component.

When passing functions to Hooks, ensure stable references to prevent unnecessary re-renders. Use useCallback() for memoization. Arrays and objects are automatically memoized.

queryHook · (query: string, hook: (value: string) => void) => void

Function called every time the query changes.

See queryHook for detail.

JavaScript

const queryHook = (query, search) => {
  search(query);
};

function SearchBox() {
  const searchBoxApi = useSearchBox({
    // ...
    queryHook,
  });

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

import type { UseSearchBoxProps } from "react-instantsearch";

const queryHook: UseSearchBoxProps["queryHook"] = (query, search) => {
  search(query);
};

function SearchBox() {
  const searchBoxApi = useSearchBox({
    // ...
    queryHook,
  });

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

APIs

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

query · string

The query from the last search.

refine · (value: string) => void

Sets a new query and searches.

clear · () => void

Clears the query and searches.

isSearchStalled · boolean · deprecated

Use status from useInstantSearch instead.

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

JavaScript

import React, { useState, useRef } from "react";
import { useInstantSearch, useSearchBox } from "react-instantsearch";

function CustomSearchBox(props) {
  const { query, refine } = useSearchBox(props);
  const { status } = useInstantSearch();
  const [inputValue, setInputValue] = useState(query);
  const inputRef = useRef(null);

  const isSearchStalled = status === "stalled";

  function setQuery(newQuery) {
    setInputValue(newQuery);

    refine(newQuery);
  }

  return (
    <div>
      <form
        action=""
        role="search"
        noValidate
        onSubmit={(event) => {
          event.preventDefault();
          event.stopPropagation();

          if (inputRef.current) {
            inputRef.current.blur();
          }
        }}
        onReset={(event) => {
          event.preventDefault();
          event.stopPropagation();

          setQuery("");

          if (inputRef.current) {
            inputRef.current.focus();
          }
        }}
      >
        <input
          ref={inputRef}
          autoComplete="off"
          autoCorrect="off"
          autoCapitalize="off"
          placeholder="Search for products"
          spellCheck={false}
          maxLength={512}
          type="search"
          value={inputValue}
          onChange={(event) => {
            setQuery(event.currentTarget.value);
          }}
          autoFocus
        />
        <button type="submit">Submit</button>
        <button
          type="reset"
          hidden={inputValue.length === 0 || isSearchStalled}
        >
          Reset
        </button>
        <span hidden={!isSearchStalled}>Searching…</span>
      </form>
    </div>
  );
}

import React, { useState, useRef } from "react";
import {
  useInstantSearch,
  useSearchBox,
  UseSearchBoxProps,
} from "react-instantsearch";

function CustomSearchBox(props: UseSearchBoxProps) {
  const { query, refine } = useSearchBox(props);
  const { status } = useInstantSearch();
  const [inputValue, setInputValue] = useState(query);
  const inputRef = useRef<HTMLInputElement>(null);

  const isSearchStalled = status === "stalled";

  function setQuery(newQuery: string) {
    setInputValue(newQuery);

    refine(newQuery);
  }

  return (
    <div>
      <form
        action=""
        role="search"
        noValidate
        onSubmit={(event) => {
          event.preventDefault();
          event.stopPropagation();

          if (inputRef.current) {
            inputRef.current.blur();
          }
        }}
        onReset={(event) => {
          event.preventDefault();
          event.stopPropagation();

          setQuery("");

          if (inputRef.current) {
            inputRef.current.focus();
          }
        }}
      >
        <input
          ref={inputRef}
          autoComplete="off"
          autoCorrect="off"
          autoCapitalize="off"
          placeholder="Search for products"
          spellCheck={false}
          maxLength={512}
          type="search"
          value={inputValue}
          onChange={(event) => {
            setQuery(event.currentTarget.value);
          }}
          autoFocus
        />
        <button type="submit">Submit</button>
        <button
          type="reset"
          hidden={inputValue.length === 0 || isSearchStalled}
        >
          Reset
        </button>
        <span hidden={!isSearchStalled}>Searching…</span>
      </form>
    </div>
  );
}