Basic Usage

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

<InstantSearch<MyUiState>
  searchClient={searchClient}
  indexName="products"
  insights={true}
  routing={true}
  stalledSearchDelay={300}
  future={{
    preserveSharedStateOnUnmount: true,
  }}
  onStateChange={({ uiState, setUiState }) => {
    console.log('State changed:', uiState);
    setUiState(uiState);
  }}
>
  {/* Your components */}
</InstantSearch>

import { SearchBox } from 'react-instantsearch';

<SearchBox
  placeholder="Search products..."
  searchAsYouType={true}
  autoFocus={true}
  ignoreCompositionEvents={false}
  translations={{
    submitButtonTitle: 'Submit search',
    resetButtonTitle: 'Clear search',
  }}
  classNames={{
    root: 'my-SearchBox',
    form: 'my-SearchBox-form',
    input: 'my-SearchBox-input',
  }}
/>

import { Hits } from 'react-instantsearch';
import type { Hit } from 'instantsearch.js';

type ProductHit = Hit<{
  name: string;
  price: number;
  image: string;
}>;

function HitComponent({ hit, sendEvent }: { hit: ProductHit; sendEvent: Function }) {
  return (
    <article
      onClick={() => {
        sendEvent('click', hit, 'Product Clicked');
      }}
    >
      <img src={hit.image} alt={hit.name} />
      <h3>{hit.name}</h3>
      <span>${hit.price}</span>
    </article>
  );
}

<Hits
  hitComponent={HitComponent}
  transformItems={(items) => 
    items.map(item => ({
      ...item,
      price: item.price / 100, // Convert cents to dollars
    }))
  }
  classNames={{
    root: 'my-Hits',
    list: 'my-Hits-list',
    item: 'my-Hits-item',
  }}
/>

import { Highlight } from 'react-instantsearch';

<Highlight
  attribute="name"
  hit={hit}
  highlightedTagName="mark"
  classNames={{
    root: 'my-Highlight',
    highlighted: 'my-Highlight-highlighted',
  }}
/>

import { RefinementList } from 'react-instantsearch';

<RefinementList
  attribute="brand"
  searchable={true}
  searchablePlaceholder="Search brands..."
  showMore={true}
  showMoreLimit={20}
  limit={10}
  operator="or"
  sortBy={['name:asc']}
  transformItems={(items) =>
    items.map(item => ({
      ...item,
      label: item.label.toUpperCase(),
    }))
  }
  translations={{
    showMoreButtonText: ({ isShowingMore }) =>
      isShowingMore ? 'Show less' : 'Show more',
    noResultsText: 'No brands found',
  }}
/>

import { Pagination } from 'react-instantsearch';

<Pagination
  totalPages={10}
  padding={2}
  showFirst={true}
  showPrevious={true}
  showNext={true}
  showLast={true}
  translations={{
    firstPageItemText: 'First',
    previousPageItemText: 'Previous',
    nextPageItemText: 'Next',
    lastPageItemText: 'Last',
    pageItemText: ({ currentPage, nbPages }) => `${currentPage} of ${nbPages}`,
  }}
/>

import { Configure } from 'react-instantsearch';

<Configure
  hitsPerPage={20}
  attributesToSnippet={['description:50']}
  snippetEllipsisText="..."
  removeWordsIfNoResults="allOptional"
  distinct={1}
  enablePersonalization={true}
/>

import { HierarchicalMenu } from 'react-instantsearch';

<HierarchicalMenu
  attributes={[
    'categories.lvl0',
    'categories.lvl1',
    'categories.lvl2',
  ]}
  separator=" > "
  showMore={true}
  limit={10}
/>

import { Menu } from 'react-instantsearch';

<Menu
  attribute="category"
  showMore={true}
  limit={5}
  showMoreLimit={15}
  sortBy={['name:asc']}
/>

import { RangeInput } from 'react-instantsearch';

<RangeInput
  attribute="price"
  min={0}
  max={1000}
  precision={2}
  translations={{
    separatorElementText: 'to',
    submitButtonText: 'Apply',
  }}
/>

import { ToggleRefinement } from 'react-instantsearch';

<ToggleRefinement
  attribute="free_shipping"
  label="Free shipping"
  on={true}
  off={false}
/>

import { CurrentRefinements } from 'react-instantsearch';

<CurrentRefinements
  excludedAttributes={['query']}
  transformItems={(items) =>
    items.filter(item => item.attribute !== 'category')
  }
/>

import { ClearRefinements } from 'react-instantsearch';

<ClearRefinements
  excludedAttributes={['category']}
  translations={{
    resetButtonText: 'Clear all filters',
  }}
/>

import { Stats } from 'react-instantsearch';

<Stats
  translations={{
    rootElementText({ nbHits, processingTimeMS }) {
      return `${nbHits.toLocaleString()} results found in ${processingTimeMS}ms`;
    },
  }}
/>

import { SortBy } from 'react-instantsearch';

<SortBy
  items={[
    { label: 'Relevance', value: 'products' },
    { label: 'Price (asc)', value: 'products_price_asc' },
    { label: 'Price (desc)', value: 'products_price_desc' },
  ]}
/>

import { Index, Hits } from 'react-instantsearch';

<InstantSearch searchClient={searchClient} indexName="products">
  <SearchBox />
  
  {/* Main index */}
  <Hits />
  
  {/* Secondary index */}
  <Index indexName="categories">
    <Hits hitComponent={CategoryHit} />
  </Index>
</InstantSearch>

import { useInstantSearch } from 'react-instantsearch';

function ConditionalWidget() {
  const { results } = useInstantSearch();
  
  if (!results || results.nbHits === 0) {
    return <p>No results found</p>;
  }
  
  return <Hits />;
}

<Hits
  transformItems={(items) =>
    items.map((item, index) => ({
      ...item,
      position: index + 1,
      discounted: item.price < item.originalPrice,
    }))
  }
  hitComponent={HitComponent}
/>

<SearchBox
  classNames={{
    root: 'search-box',
    form: 'search-box__form',
    input: 'search-box__input',
    submit: 'search-box__submit',
    reset: 'search-box__reset',
    loadingIndicator: 'search-box__loading',
  }}
/>