> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.
# hits
> Shows a list of search results.
```ts Signature theme={"system"}
hits({
container: string | HTMLElement,
// Optional parameters
escapeHTML?: boolean,
templates?: object,
cssClasses?: object,
transformItems?: function,
});
```
## Import
```js Package manager theme={"system"}
import { hits } from "instantsearch.js/es/widgets";
```
```js CDN theme={"system"}
const { hits } = instantsearch.widgets;
// or directly use instantsearch.widgets.hits()
```
Preview this widget and its behavior.
## About this widget
Use the `hits` widget to display a list of search results.
To set the number of search results,
use the [`hitsPerPage`](/doc/api-reference/widgets/hits-per-page/js)
or [`configure`](/doc/api-reference/widgets/configure/js) widget.
See also:
* [Structured results](/doc/guides/building-search-ui/ui-and-ux-patterns/structured-results/js)
* [Multi-index search](/doc/guides/building-search-ui/ui-and-ux-patterns/multi-index-search/js)
* [Searches without results](/doc/guides/building-search-ui/going-further/conditional-display/js#handling-no-results)
## Examples
```js JavaScript icon=code theme={"system"}
hits({
container: "#hits",
templates: {
item(hit, { html, components }) {
return html`
${components.Highlight({ attribute: "name", hit })}
${hit.description}
`;
},
},
});
```
## Options
The CSS Selector or `HTMLElement` to insert the widget into.
```js string theme={"system"}
hits({
container: "#hits",
});
```
```js HTMLElement theme={"system"}
hits({
container: document.querySelector("#hits"),
});
```
Escapes HTML entities from hits string values.
```js JavaScript icon=code theme={"system"}
hits({
// ...
escapeHTML: false,
});
```
The [templates](#templates) to use for the widget.
```js JavaScript icon=code theme={"system"}
hits({
// ...
templates: {
// ...
},
});
```
The [CSS classes you can override](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#style-your-widgets):
* `root`. The widget's root element.
* `emptyRoot`. The container 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.
```js JavaScript icon=code theme={"system"}
hits({
// ...
cssClasses: {
root: "MyCustomHits",
list: ["MyCustomHitsList", "MyCustomHitsList--subclass"],
},
});
```
items"]}>
A function that receives the list of items before they are displayed.
It should return a new array with the same structure.
Use this to transform, filter, or reorder the items.
The function also has access to the full `results` data,
including all standard [response parameters](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
such as `disjunctiveFacetsRefinements`.
If you transform an attribute used in the [`highlight`](/doc/api-reference/widgets/highlight/js) widget,
you must also transform the corresponding `item._highlightResult[attribute].value`.
```js JavaScript icon=code theme={"system"}
hits({
// ...
transformItems(items) {
return items.map((item) => ({
...item,
name: item.name.toUpperCase(),
}));
},
});
// or, combined with results
hits({
// ...
transformItems(items, { results }) {
return items.map((item, index) => ({
...item,
position: { index, page: results.page },
}));
},
});
```
## Templates
You can customize parts of a widget’s UI using the Templates API.
Each template includes an `html` function,
which you can use as a [tagged template](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#tagged_templates).
This function safely renders templates as HTML strings and works directly in the browser—no build step required.
For details, see [Templating your UI](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js/#templating-your-ui).
The `html` function is available in InstantSearch.js version 4.46.0 or later.
The template to use when there are no results. It exposes the `results` object.
```js function theme={"system"}
hits({
// ...
templates: {
empty(results, { html }) {
return html`No results for ${results.query}`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
hits({
// ...
templates: {
empty: "No results for {{ query }}",
},
});
```
The template to use for each result.
This template receives an object containing a single record.
The record has a new property `__hitIndex` for the relative position of the record in the list of displayed hits.
You can use [Algolia's highlighting feature](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#highlight-and-snippet-your-search-results) with the [`highlight`]() function, directly from the [template system](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#templating-your-ui).
```js JavaScript icon=code theme={"system"}
hits({
// ...
templates: {
item(hit, { html, components }) {
return html`
${hit.__hitIndex}: ${components.Highlight({ attribute: "name", hit })}
${hit.description}
`;
},
},
});
```
The template to use for the banner.
This template receives an object containing the `banner` data returned within the `renderingContent` property from the Algolia API response and a `classNames` object representing the CSS classes provided to the widget.
It is rendered above the results.
```js function theme={"system"}
hits({
// ...
templates: {
banner({ banner }, { html }) {
return html``;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
hits({
// ...
templates: {
banner: ``,
},
});
```
## HTML output
```html HTML icon=code-xml theme={"system"}
...
...
...
```
## Customize the UI with `connectHits`
If you want to create your own UI of the `hits` widget, you can use connectors.
To use `connectHits`, you can import it with the declaration relevant to how you installed InstantSearch.js.
```js Package manager theme={"system"}
import { connectHits } from "instantsearch.js/es/connectors";
```
```js CDN theme={"system"}
const { connectHits } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectHits()
```
Then it's a 3-step process:
```js JavaScript icon=code theme={"system"}
// 1. Create a render function
const renderHits = (renderOptions, isFirstRender) => {
// Rendering logic
};
// 2. Create the custom widget
const customHits = connectHits(renderHits);
// 3. Instantiate
search.addWidgets([
customHits({
// instance params
}),
]);
```
### Create a render function
This rendering function is called before the first search (`init` lifecycle step)
and each time results come back from Algolia (`render` lifecycle step).
```js JavaScript icon=code theme={"system"}
const renderHits = (renderOptions, isFirstRender) => {
const { items, results, banner, sendEvent, widgetParams } = renderOptions;
if (isFirstRender) {
// Do some initial rendering and bind events
}
// Render the widget
};
```
#### Render options
The matched hits from the Algolia API. You can use [Algolia's highlighting feature](/doc/guides/building-search-ui/widgets/customize-an-existing-widget/js#highlight-and-snippet-your-search-results) with the [`highlight`]() function, directly from the connector's render function.
```js JavaScript icon=code theme={"system"}
const renderHits = (renderOptions, isFirstRender) => {
const { items } = renderOptions;
document.querySelector("#hits").innerHTML = `
`;
};
```
The complete response from the Algolia API. It contains the `hits`, metadata about the page, the number of hits, and so on. Unless you need to access metadata, use `items` instead. You should also consider the [`stats`]() widget if you want to build a widget that displays metadata about the search.
```js JavaScript icon=code theme={"system"}
const renderHits = (renderOptions, isFirstRender) => {
const { results } = renderOptions;
if (isFirstRender) {
return;
}
document.querySelector("#hits").innerHTML = `
${results.hits.map((item) => `
${item.name}
`).join("")}
`;
};
```
The banner data returned within the `renderingContent` property from the Algolia API response. It is rendered above the results by default and can be used to display promotional content.
```js JavaScript icon=code theme={"system"}
const renderHits = (renderOptions, isFirstRender) => {
const { items, banner } = renderOptions;
document.querySelector("#hits").innerHTML = `
`;
};
```
The function to send `click` or `conversion` events.
The `view` event is automatically sent when this connector renders hits.
* `eventType: 'click' | 'conversion'`
* `hit: Hit | Hit[]`
* `eventName: string`
For more about these events, see the [`insights`](/doc/api-reference/widgets/insights/js) middleware documentation.
```js Example theme={"system"}
// For example,
sendEvent("click", hit, "Product Added");
// or
sendEvent("conversion", hit, "Order Completed");
/*
A payload like the following will be sent to the `insights` middleware.
{
eventType: 'click',
insightsMethod: 'clickedObjectIDsAfterSearch',
payload: {
eventName: 'Product Added',
index: '',
objectIDs: [''],
positions: [],
queryID: '',
},
widgetType: 'ais.hits',
}
*/
```
All original widget options forwarded to the render function.
```js JavaScript icon=code theme={"system"}
const renderHits = (renderOptions, isFirstRender) => {
const { widgetParams } = renderOptions;
widgetParams.container.innerHTML = "...";
};
// ...
search.addWidgets([
customHits({
container: document.querySelector("#hits"),
}),
]);
```
### Create and instantiate the custom widget
First, create your custom widgets using a rendering function.
Then, instantiate them with parameters.
There are two kinds of parameters you can pass:
* **Instance parameters**. Predefined options that configure Algolia's behavior.
* **Custom parameters**. Parameters you define to make the widget reusable and adaptable.
Inside the `renderFunction`, both instance and custom parameters are accessible through `connector.widgetParams`.
```js JavaScript icon=code theme={"system"}
const customHits = connectHits(renderHits);
search.addWidgets([
customHits({
// Optional parameters
escapeHTML,
transformItems,
}),
]);
```
#### Instance options
Escapes HTML entities from hits string values.
```js JavaScript icon=code theme={"system"}
customHits({
escapeHTML: false,
});
```
items"]}>
A function that receives the list of items before they are displayed.
It should return a new array with the same structure.
Use this to transform, filter, or reorder the items.
The function also has access to the full `results` data,
including all standard [response parameters](/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/)
and [parameters from the helper](https://community.algolia.com/algoliasearch-helper-js/reference.html#query-parameters),
such as `disjunctiveFacetsRefinements`.
If you transform an attribute used in the [`highlight`](/doc/api-reference/widgets/highlight/js) widget,
you must also transform the corresponding `item._highlightResult[attribute].value`.
```js JavaScript icon=code theme={"system"}
customHits({
transformItems(items) {
return items.map((item) => ({
...item,
name: item.name.toUpperCase(),
}));
},
});
// or: combined with results
customHits({
transformItems(items, { results }) {
return items.map((item, index) => ({
...item,
position: { index, page: results.page },
}));
},
});
```
### Full example
```html HTML theme={"system"}
```
```js JavaScript theme={"system"}
// Create the render function
const renderHits = (renderOptions, isFirstRender) => {
const { items, widgetParams } = renderOptions;
widgetParams.container.innerHTML = `
`;
};
// Create the custom widget
const customHits = connectHits(renderHits);
// Instantiate the custom widget
search.addWidgets([
customHits({
container: document.querySelector("#hits"),
}),
]);
```
## Click and conversion events
If the [`insights`](/doc/api-reference/widgets/instantsearch/js#param-insights) option is `true`,
the `hits` widget automatically sends a `click` event with the following shape to the Insights API whenever users click a hit.
```jsonc JSON icon=braces theme={"system"}
{
"eventType": "click",
"insightsMethod": "clickedObjectIDsAfterSearch",
"payload": {
"eventName": "Hit Clicked"
// …
},
"widgetType": "ais.hits"
}
```
To customize this event, use the `sendEvent` function in your [`item`](#param-item) template and send a custom `click` event.
```js JavaScript icon=code theme={"system"}
hits({
templates: {
item(hit, { html, components, sendEvent }) {
return html`
${components.Highlight({ attribute: "name", hit })}
${hit.description}
`;
},
},
});
```
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.
```js JavaScript icon=code theme={"system"}
hits({
templates: {
item(hit, { html, components, sendEvent }) {
return html`
${components.Highlight({ attribute: "name", hit })}
${hit.description}
`;
},
},
});
```
Use strings to represent monetary values in major currency units (for example, '5.45').
This avoids floating-point rounding issues, especially when performing calculations.
See also: [Send click and conversion events with InstantSearch.js](/doc/guides/building-search-ui/events/js)
`;
},
},
});
```
```js string theme={"system"}
// String-based templates are deprecated, use functions instead.
hits({
// ...
templates: {
banner: `