hits

Signature

hits({
  container: string | HTMLElement,
  // Optional parameters
  escapeHTML?: boolean,
  templates?: object,
  cssClasses?: object,
  transformItems?: function,
});

Import

import { hits } from "instantsearch.js/es/widgets";

const { hits } = instantsearch.widgets;
// or directly use instantsearch.widgets.hits()

See this widget in action

Preview this widget and its behavior.

Use the hits widget to display a list of search results. To set the number of search results, use the hitsPerPage or configure widget. See also:

Examples

JavaScript

hits({
  container: "#hits",
  templates: {
    item(hit, { html, components }) {
      return html`
        <h2>${components.Highlight({ attribute: "name", hit })}</h2>
        <p>${hit.description}</p>
      `;
    },
  },
});

Options

container

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

hits({
  container: "#hits",
});

hits({
  container: document.querySelector("#hits"),
});

escapeHTML

boolean

default:true

Escapes HTML entities from hits string values.

JavaScript

hits({
  // ...
  escapeHTML: false,
});

templates

object

The templates to use for the widget.

JavaScript

hits({
  // ...
  templates: {
    // ...
  },
});

cssClasses

object

default:"{}"

The CSS classes you can override:

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.

JavaScript

hits({
  // ...
  cssClasses: {
    root: "MyCustomHits",
    list: ["MyCustomHitsList", "MyCustomHitsList--subclass"],
  },
});

transformItems

function

default: items => 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 and parameters from the helper, such as disjunctiveFacetsRefinements.If you transform an attribute used in the highlight widget, you must also transform the corresponding item._highlightResult[attribute].value.

JavaScript

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. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

empty

string | function

The template to use when there are no results. It exposes the results object.

hits({
  // ...
  templates: {
    empty(results, { html }) {
      return html`No results for <q>${results.query}</q>`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
hits({
  // ...
  templates: {
    empty: "No results for <q>{{ query }}</q>",
  },
});

item

string | function

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 with the highlight function, directly from the template system.

JavaScript

hits({
  // ...
  templates: {
    item(hit, { html, components }) {
      return html`
        <h2>
          ${hit.__hitIndex}: ${components.Highlight({ attribute: "name", hit })}
        </h2>
        <p>${hit.description}</p>
      `;
    },
  },
});

banner

string | function

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.

hits({
  // ...
  templates: {
    banner({ banner }, { html }) {
      return html`<img src="${banner.image.urls[0].url}" />`;
    },
  },
});

// String-based templates are deprecated, use functions instead.
hits({
  // ...
  templates: {
    banner: `<img src="${banner.image.urls[0].url}" />`,
  },
});

HTML output

HTML

<div class="ais-Hits">
  <aside class="ais-Hits-banner">
    <a class="ais-Hits-banner-link">
      <img class="ais-Hits-banner-image" />
    </a>
  </aside>
  <ol class="ais-Hits-list">
    <li class="ais-Hits-item">...</li>
    <li class="ais-Hits-item">...</li>
    <li class="ais-Hits-item">...</li>
  </ol>
</div>

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.

import { connectHits } from "instantsearch.js/es/connectors";

const { connectHits } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectHits()

Then it’s a 3-step process:

JavaScript

// 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).

JavaScript

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

items

object[]

The matched hits from the Algolia API. You can use Algolia’s highlighting feature with the highlight function, directly from the connector’s render function.

JavaScript

const renderHits = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

  document.querySelector("#hits").innerHTML = `
    <ul>
      ${items
        .map(
          (item) =>
            `<li>
              ${instantsearch.highlight({ attribute: "name", hit: item })}
            </li>`,
        )
        .join("")}
    </ul>
  `;
};

results

object

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.

JavaScript

const renderHits = (renderOptions, isFirstRender) => {
  const { results } = renderOptions;

  if (isFirstRender) {
    return;
  }

  document.querySelector("#hits").innerHTML = `
    <ul>
      ${results.hits.map((item) => `<li>${item.name}</li>`).join("")}
    </ul>
  `;
};

banner

object

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.

JavaScript

const renderHits = (renderOptions, isFirstRender) => {
  const { items, banner } = renderOptions;

  document.querySelector("#hits").innerHTML = `
    <img src="${banner.image.urls[0].url}" />
    <ul>
      ${items
        .map(
          (item) =>
            `<li>
              ${instantsearch.highlight({ attribute: "name", hit: item })}
            </li>`,
        )
        .join("")}
    </ul>
  `;
};

sendEvent

(eventType, hit, eventName) => void

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 middleware documentation.

Example

// 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: '<index-name>',
      objectIDs: ['<object-id>'],
      positions: [<position>],
      queryID: '<query-id>',
    },
    widgetType: 'ais.hits',
  }
*/

All original widget options forwarded to the render function.

JavaScript

const renderHits = (renderOptions, isFirstRender) => {
  const { widgetParams } = renderOptions;

  widgetParams.container.innerHTML = "...";
};

// ...

search.addWidgets([
  customHits({
    container: document.querySelector("#hits"),
  }),
]);

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.

JavaScript

const customHits = connectHits(renderHits);

search.addWidgets([
  customHits({
    // Optional parameters
    escapeHTML,
    transformItems,
  }),
]);

Instance options

escapeHTML

boolean

default:true

Escapes HTML entities from hits string values.

JavaScript

customHits({
  escapeHTML: false,
});

transformItems

function

default: items => items

JavaScript

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

<div id="hits"></div>

// Create the render function
const renderHits = (renderOptions, isFirstRender) => {
  const { items, widgetParams } = renderOptions;

  widgetParams.container.innerHTML = `
    <ul>
      ${items
        .map(
          (item) =>
            `<li>
              ${instantsearch.highlight({ attribute: "name", hit: item })}
            </li>`,
        )
        .join("")}
    </ul>
  `;
};

// 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 option is true, the hits widget automatically sends a click event with the following shape to the Insights API whenever users click a hit.

JSON

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

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

JavaScript

hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <div onClick="${() => sendEvent("click", hit, "Product Clicked")}">
          <h2>${components.Highlight({ attribute: "name", 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.

JavaScript

hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <div>
          <h2>${components.Highlight({ attribute: "name", 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>
      `;
    },
  },
});

Use strings to represent monetary values in major currency units (for example, ‘5.45’). This avoids floating-point rounding issues, especially when performing calculations.

Import

See this widget in action

About this widget

Examples

Options

Templates

HTML output

Customize the UI with `connectHits`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example

Click and conversion events

​Import

See this widget in action

​About this widget

​Examples

​Options

​Templates

​HTML output

​Customize the UI with connectHits

​Create a render function

​Render options

​Create and instantiate the custom widget

​Instance options

​Full example

​Click and conversion events

Import

About this widget

Examples

Options

Templates

HTML output

Customize the UI with `connectHits`

Create a render function

Render options

Create and instantiate the custom widget

Instance options

Full example

Click and conversion events