<Hits>
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.
<Hits // Optional props hitComponent={({ hit }) => JSX.Element} classNames={object} ...props={ComponentProps<'div'>} />
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 When not provided, the widget displays the hit as a JSON string. |
||
Copy
|
|||
bannerComponent
|
type: ((props: { banner: SearchResults['renderingContent']['widgets']['banners'][0] }) => JSX.Element) | false
Optional
A component that renders the banner data on the When |
||
Copy
|
|||
escapeHTML
|
type: boolean
default: true
Optional
Whether to escape HTML tags from hits string values. |
||
Copy
|
|||
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 The complete If you’re transforming an attribute you’re using with the |
||
Copy
|
|||
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.
|
||
Copy
|
|||
...props
|
type: React.ComponentProps<'div'>
Optional
Any |
||
Copy
|
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. |
||
Copy
|
|||
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 The complete If you’re transforming an attribute with the |
||
Copy
|
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 |
banner
|
type: SearchResults<THit>['renderingContent']['widgets']['banners'][0]
The banner data on the |
sendEvent
|
type: (eventType: string, hits: Hit | Hits, eventName?: string) => void
The function to send The |
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.