Skip to main content
The <InstantSearch> component is the root component that manages the search state and provides it to all child components.

​
Import

import { InstantSearch } from 'react-instantsearch';

​
Props

​
searchClient
SearchClient
required
The Algolia search client created with algoliasearch().
import { liteClient as algoliasearch } from 'algoliasearch/lite';

const searchClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);
Create the search client outside your component to avoid re-creating it on every render. Re-creating the client causes unnecessary search requests.
​
indexName
string
required
The main index to search in.
<InstantSearch indexName="products" searchClient={searchClient}>
  {/* ... */}
</InstantSearch>
​
initialUiState
UiState
The initial UI state of the search interface. Use this to set initial query, refinements, pagination, etc.
<InstantSearch
  searchClient={searchClient}
  indexName="products"
  initialUiState={{
    products: {
      query: 'iphone',
      refinementList: {
        brand: ['Apple'],
      },
      page: 1,
    },
  }}
>
  {/* ... */}
</InstantSearch>
​
routing
boolean | object
Enable URL routing to sync the search state with the browser URL.
// Simple routing
<InstantSearch routing={true} {/* ... */}>
  {/* ... */}
</InstantSearch>

// Custom routing
<InstantSearch
  routing={{
    router: createNextRouter(),
    stateMapping: createInstantSearchRouterNext({
      routerOptions: { basePath: '/search' },
    }),
  }}
>
  {/* ... */}
</InstantSearch>
​
onStateChange
(params: { uiState: UiState; setUiState: Function }) => void
Called when the search state changes. Useful for tracking or syncing state.
<InstantSearch
  onStateChange={({ uiState, setUiState }) => {
    // Track state changes
    console.log('Search state changed:', uiState);
    
    // Update state normally
    setUiState(uiState);
  }}
>
  {/* ... */}
</InstantSearch>
​
searchFunction
(helper: Helper) => void
Override the search function to control when searches are triggered.
<InstantSearch
  searchFunction={(helper) => {
    // Only search if query is not empty
    if (helper.state.query) {
      helper.search();
    }
  }}
>
  {/* ... */}
</InstantSearch>
​
stalledSearchDelay
number
default:"200"
Time in milliseconds before a search is considered stalled. Used for showing loading indicators.
<InstantSearch stalledSearchDelay={500}>
  {/* ... */}
</InstantSearch>
​
future
object
Opt-in to future breaking changes to prepare for the next major version.
<InstantSearch
  future={{
    preserveSharedStateOnUnmount: true,
  }}
>
  {/* ... */}
</InstantSearch>
​
children
ReactNode
The child components, typically search widgets.

​
Example

import { InstantSearch, SearchBox, Hits, RefinementList } from 'react-instantsearch';
import { liteClient as algoliasearch } from 'algoliasearch/lite';

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

function App() {
  return (
    <InstantSearch
      searchClient={searchClient}
      indexName="products"
      routing={true}
      initialUiState={{
        products: {
          query: '',
        },
      }}
    >
      <div className="container">
        <div className="search-panel">
          <div className="search-panel__filters">
            <RefinementList attribute="brand" />
          </div>
          <div className="search-panel__results">
            <SearchBox placeholder="Search products..." />
            <Hits />
          </div>
        </div>
      </div>
    </InstantSearch>
  );
}

​
With TypeScript

import { InstantSearch } from 'react-instantsearch';
import type { UiState } from 'instantsearch.js';

interface MyUiState extends UiState {
  products: {
    query?: string;
    refinementList?: {
      brand?: string[];
      category?: string[];
    };
  };
}

function App() {
  return (
    <InstantSearch<MyUiState>
      searchClient={searchClient}
      indexName="products"
    >
      {/* ... */}
    </InstantSearch>
  );
}

Build docs developers (and LLMs) love

Get started for freeTalk to us