UI libraries / React InstantSearch Hooks / Widgets

<Hits>

Signature 
<Hits
  // Optional props
  hitComponent={({ hit }) => JSX.Element}
  classNames={object}
  ...props={ComponentProps<'div'>}
/>
Import
Copy 
1

import { Hits } from 'react-instantsearch-hooks-web';
See code examples
See live example

About this widget

<Hits> is a widget that lets you display a list of results.

To configure the number of retrieved hits, use the <HitsPerPage> widget or pass the hitsPerPage prop to the <Configure> widget.

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

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

import React from 'react';
import algoliasearch from 'algoliasearch/lite';
import { InstantSearch, Hits } from 'react-instantsearch-hooks-web';

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.
Copy 
1

<Hits hitComponent={({ hit }) => hit.objectID} />
escapeHTML
type: boolean
default: true
Optional

Whether to escape HTML tags from hits string values.
Copy 
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. Should return a new array with the same shape as the original array. Useful for transforming or reordering items. Don’t use transformItems to remove items, since this will impact your pagination.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).

If you’re transforming an attribute you’re using with the <Highlight> widget, you also need to transform item._highlightResult[attribute].value.
Copy 
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

CSS classes to pass to the widget’s elements. This is useful to style widgets with class-based CSS frameworks like Bootstrap or Tailwind CSS.

  • root: The root element of the widget.
  • emptyRoot: The root element without results.
  • list: The list of results.
  • item: The list items.
Copy 
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 root element of the widget.
Copy 
1

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

Hook

React InstantSearch Hooks 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.

See code examples

Usage

First, create your React component:

import { useHits } from 'react-instantsearch-hooks-web';

function CustomHits(props) {
  const { hits, results, 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.
Copy 
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. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).

If you’re transforming an attribute you’re using with the <Highlight> widget, you also need to transform item._highlightResult[attribute].value.
Copy 
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.

hits
type: THit[]

The matched hits returned from Algolia.

You can leverage the highlighting feature of Algolia 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, you should use hits instead.
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

Copy 
1
2
3
4
5
6
7
8

import React from 'react';
import { useHits } from 'react-instantsearch-hooks-web';

function CustomHits(props) {
  const { hits } = useHits(props);

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

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 the end user clicks on a hit.

Copy 
1
2
3
4
5
6
7
8
9

{
  eventType: 'click',
  insightsMethod: 'clickedObjectIDsAfterSearch',
  payload: {
    eventName: 'Hit Clicked',
    // …
  },
  widgetType: 'ais.hits',
}

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

Copy 
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>
  )}
/>;
Guide Send click and conversion events with React InstantSearch Hooks
Did you find this page helpful?
React InstantSearch Hooks v6