UI libraries / React InstantSearch / Widgets

This is the React InstantSearch v7 documentation. React InstantSearch v7 is the latest version of React InstantSearch and the stable version of React InstantSearch Hooks.

If you were using React InstantSearch v6, you can upgrade to v7.

If you were using React InstantSearch Hooks, you can still use the React InstantSearch v7 documentation, but you should check the upgrade guide for necessary changes.

If you want to keep using React InstantSearch v6, you can find the archived documentation.

Signature
<Hits
  // Optional props
  hitComponent={({ hit }) => JSX.Element}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>
Import
1
import { Hits } from 'react-instantsearch';

About this widget

Use the <Hits> widget to display a list of search results.

To set the number of search results, use the <HitsPerPage> widget or pass the hitsPerPage prop to the <Configure> widget.

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

Examples

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
import React from 'react';
import { liteClient as algoliasearch } from 'algoliasearch/lite';
import { InstantSearch, Hits } from 'react-instantsearch';

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

function Hit({ hit }) {
  return JSON.stringify(hit);
}

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

Props

hitComponent
type: (props: { hit: THit; sendEvent: SendEventForHits }) => JSX.Element
Optional

A component that renders each hit from the results. It receives a hit and a sendEvent (for insights) prop.

When not provided, the widget displays the hit as a JSON string.

1
<Hits hitComponent={({ hit }) => hit.objectID} />
bannerComponent
type: ((props: { banner: SearchResults['renderingContent']['widgets']['banners'][0] }) => JSX.Element) | false
Optional

A component that renders the banner data on the renderingContent property from the Algolia response. It overrides the default banner rendering.

When false, the widget does not render the banner.

1
2
3
4
5
6
7
8
9
10
11
// Override the default banner rendering
<Hits
  // ...
  bannerComponent={({ banner }) => <img src={banner.image.urls[0].url} />}
/>

// Disable the banner rendering
<Hits
  // ...
  bannerComponent={false}
/>
escapeHTML
type: boolean
default: true
Optional

Whether to escape HTML tags from hits string values.

1
2
3
4
<Hits
  // ...
  escapeHTML={false}
/>
transformItems
type: (items: object[], metadata: { results: SearchResults }) => object[]
Optional

Receives the items and is called before displaying them. It returns a new array with the same “shape” as the original. This is helpful when transforming or reordering items. Don’t use transformItems to remove items since this will affect your pagination.

The complete results data is also available, including all regular response parameters and helper parameters (for example, disjunctiveFacetsRefinements).

If you’re transforming an attribute you’re using with the <Highlight> widget, you must also transform item._highlightResult[attribute].value.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Using only items
const transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.name.toUpperCase(),
  }));
};

// Using items and results
const transformItems = (items, { results }) => {
  return items.map((item, index) => ({
    ...item,
    position: { index, page: results.page },
  }));
};

function Search() {
  return (
    <Hits
      // ...
      transformItems={transformItems}
    />
  );
}
classNames
type: Partial<HitsClassNames>
Optional

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 widget’s root element.
  • emptyRoot: the root element without results.
  • list: the list of results.
  • item: the list of items.
  • bannerRoot: the root element of the banner.
  • bannerImage: the image element of the banner.
  • bannerLink: the anchor element of the banner.
1
2
3
4
5
6
7
<Hits
  // ...
  classNames={{
    root: 'MyCustomHits',
    list: 'MyCustomHitsList MyCustomHitsList--subclass',
  }}
/>
...props
type: React.ComponentProps<'div'>
Optional

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

1
<Hits className="MyCustomHits" title="My custom title" />

Hook

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

The useHits() Hook accepts parameters and returns APIs.

Usage

First, create your React component:

import { useHits } from 'react-instantsearch';

function CustomHits(props) {
  const { items, results, banner, sendEvent } = useHits(props);

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

Then, render the widget:

<CustomHits {...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 to avoid rendering endlessly (for example, with useCallback()). Objects and arrays are memoized; you don’t need to stabilize them.

escapeHTML
type: boolean
default: true

Whether to escape HTML tags from hits string values.

1
2
3
const hitsApi = useHits({
  escapeHTML: false,
});
transformItems
type: (items: object[], metadata: { results: SearchResults }) => object[]
default: items => items

Receives the items and is called before displaying them. It returns a new array with the same “shape” as the original. This is helpful when transforming or reordering items. Don’t use transformItems to remove items since this will affect your pagination.

The complete results data is also available, including all regular response parameters and helper parameters (for example, disjunctiveFacetsRefinements).

If you’re transforming an attribute with the <Highlight> widget, you must transform item._highlightResult[attribute].value.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Using only items
const transformItems = (items) => {
  return items.map((item) => ({
    ...item,
    label: item.name.toUpperCase(),
  }));
};

// Using items and results
const transformItems = (items, { results }) => {
  return items.map((item, index) => ({
    ...item,
    position: { index, page: results.page },
  }));
};

function Hits() {
  const hitsApi = useHits({
    // ...
    transformItems,
  });

  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.

items
type: THit[]

The matched items returned from Algolia.

You can use Algolia’s highlighting feature directly from the render function.

results
type: SearchResults<THit>

The complete response from Algolia.

It contains the hits but also metadata about the page, number of hits, and more. Unless you need to access metadata, use items instead.

banner
type: SearchResults<THit>['renderingContent']['widgets']['banners'][0]

The banner data on the renderingContent property from the Algolia response.

sendEvent
type: (eventType: string, hits: Hit | Hits, eventName?: string) => void

The function to send click or conversion events.

The view event is automatically sent when this Hook renders hits. Check the insights documentation to learn more.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import React from 'react';
import { useHits } from 'react-instantsearch';

function CustomHits(props) {
  const { items, sendEvent } = useHits(props);

  return (
    <ol>
      {items.map((hit) => (
        <li
          key={hit.objectID}
          onClick={() => sendEvent('click', hit, 'Hit Clicked')}
          onAuxClick={() => sendEvent('click', hit, 'Hit Clicked')}
        >
          <div style={{ wordBreak: 'break-all' }}>
            {JSON.stringify(hit).slice(0, 100)}
          </div>
        </li>
      ))}
    </ol>
  );
}

Click and conversion events

If the insights option is true, the Hits component automatically sends a click event with the following “shape” to the Insights API whenever users click a hit.

1
2
3
4
5
6
7
8
9
{
  eventType: 'click',
  insightsMethod: 'clickedObjectIDsAfterSearch',
  payload: {
    eventName: 'Hit Clicked',
    // 
  },
  widgetType: 'ais.hits',
}

To customize this event, use the sendEvent function in your hitComponent and send a custom click event.

1
2
3
4
5
6
7
8
9
10
<Hits
  hitComponent={({ hit, sendEvent }) => (
    <div onClick={() => sendEvent("click", hit, "Product Clicked")}>
      <h2>
        <Highlight attributeName="name" hit={hit} />
      </h2>
      <p>{hit.description}</p>
    </div>
  )}
/>;

The sendEvent function also accepts an object as a fourth argument to send directly to the Insights API. You can use it, for example, to send special conversion events with a subtype.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
<Hits
  hitComponent={({ hit, sendEvent }) => (
    <div>
      <h2>
        <Highlight attributeName="name" hit={hit} />
      </h2>
      <p>{hit.description}</p>
      <button
        onClick={() =>
          sendEvent('conversion', hit, 'Added To Cart', {
            // Special subtype
            eventSubtype: 'addToCart',
            // An array of objects representing each item added to the cart
            objectData: [
              {
                // The discount value for this item, if applicable
                discount: hit.discount || 0,
                // The price value for this item (minus the discount)
                price: hit.price,
                // How many of these items were added
                quantity: 2,
                // The per-item `queryID` for the query preceding this event
                queryID: hit.__queryID,
              },
            ],
            // The total value of all items
            value: hit.price * 2,
            // The currency code
            currency: 'USD',
          })
        }
      >
        Add to cart
      </button>
    </div>
  )}
/>;

Fields representing monetary values accept both numbers and strings, in major currency units (for example, 5.45 or '5.45'). To prevent floating-point math issues, use strings, especially if you’re performing calculations.

Did you find this page helpful?