> ## 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. export const FlavorSwitcher = ({current, baseHref = "", options = [], label = "InstantSearch framework"}) => { if (options.length === 0) { return

FlavorSwitcher requires at least one option.

; } const selected = options.find(option => option.value === current) ?? options[0]; return

{selected.label}

{option.label} {option.description ? {option.description} : null}

; };

```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 = `

${instantsearch.highlight({ attribute: "name", hit: item })}

`; }; ``` 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 = `

${item.name}

`; }; ``` 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 = `

${instantsearch.highlight({ attribute: "name", hit: item })}

`; }; ``` 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 = `

${instantsearch.highlight({ attribute: "name", hit: item })}

`; }; // 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)