React SDK

Styles with Tailwind v4

The components' default styles are Tailwind classes inside the package. Tailwind v4, the Next.js default, does not scan node_modules, so without one more line the components render unstyled. Add an @source line to the CSS file that imports Tailwind. The path is relative to that file.

@import "tailwindcss";
@source "../node_modules/@headband/react";

For src/app/globals.css, use "../../node_modules/@headband/react". Without Tailwind, pass styled={false} and style the components yourself.

Before you build

Each engine needs different settings before filters, facets and sorting work. Read Engine compatibility for the engine your index is on. The search key in the browser can read every field you index, so leave private fields out of your documents. See What a search key can read.

Which version

Install 0.2.1 or later; the latest is 0.3.0. The experiment helpers (assignExperiment, recordExperimentEvent), the filter helpers, the mode prop and client.warm() need 0.2.0 or later.

useSearch()

Core hook exposing the full search state and all actions. Use the specialized hooks below for most cases.

const {
  query,
  results,
  isLoading,
  error,
  setQuery,
  setPage,
  refresh,
} = useSearch();

useSearchBox()

Binds to the search input. Returns the current query plus setters.

const { query, setQuery, clear, warm } =
  useSearchBox();

// query: string
//   - Current query
// setQuery(q: string)
//   - Update query (resets pagination,
//     triggers debounced search)
// clear()
//   - Reset query to ""
// warm()
//   - Wake the index's engine. Call it
//     when your own input gets focus.

SearchBox wakes the index's engine when it gets focus, so the first search does not wait for a sleeping engine. Turn it off with warmOnFocus={false}. For any other input, call client.warmOnFocus(indexes) from its focus handler. It sends at most one warm per 10 seconds for the same indexes, never throws, and is never counted as a search.

useHits<T>()

Returns the current search hits with loading and error state. Supports generics for typed hits.

const { hits, isLoading, error } =
  useHits<Product>();

// hits: Hit<T>[]
//   - Each hit has document fields
//     + _formatted + __data
// isLoading: boolean
// error: Error | null

useRefinementList(props)

Provides facet filtering for a given attribute. Automatically registers the facet with the provider. The attribute must be filterable on the index first, or every search fails. Ticking a value keeps the other values and their counts in the list (0.2.1 and later), using one more search per facet with a ticked value.

const {
  items,
  refine,
  canToggle,
  isLoading,
} = useRefinementList({
  attribute: "category",
  // max facet values (default: 20)
  limit: 20,
  // "count" or "alpha" (default: "count")
  sortBy: "count",
});

// items: {
//   value: string,
//   count: number,
//   isRefined: boolean,
// }[]
// refine(value: string)
//   - Toggle a facet value on/off

usePagination()

Pagination state derived from the current search results.

const {
  currentPage,
  totalPages,
  totalHits,
  setPage,
  canPrevious,
  canNext,
  pages,
} = usePagination();

// pages: number[]
//   - Window of page numbers for
//     rendering a page list
// Pages are 0-indexed internally

useStats()

Returns summary stats about the current search results.

const {
  totalHits,
  processingTimeMs,
  query,
  isLoading,
} = useStats();

useSortBy({ items })

Sort-by dropdown state. Pass sort options, get back the current selection.

const {
  currentSort,
  setSort,
  items,
} = useSortBy({
  items: [
    {
      value: "price:asc",
      label: "Price (low to high)",
    },
    {
      value: "price:desc",
      label: "Price (high to low)",
    },
  ],
});

// items[n].isSelected: boolean
//   - Added to each item
// setSort(null)
//   - Reset to default relevance

useRange({ attribute })

Numeric range filter for a given attribute.

const {
  min,
  max,
  stats,
  setRange,
  clear,
  isLoading,
} = useRange({
  attribute: "price",
});

// stats: { min: number, max: number }
//        | undefined
//   - Overall min/max from engine
// setRange({ min: 10, max: 500 })
//   - Set range filter
// clear()
//   - Remove range filter

useHighlight({ hit, attribute })

Extracts the highlighted value for a specific attribute from a hit. Sanitizes HTML: only allows <em> tags.

const { value, highlighted } =
  useHighlight({
    hit,
    attribute: "title",
  });

// value: string
//   - Safe HTML string with <em> tags
// highlighted: boolean
//   - Whether the value contains
//     highlight marks

// Usage:
// <span dangerouslySetInnerHTML={{
//   __html: value,
// }} />