UI libraries / InstantSearch.js / Widgets

hits

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

import { hits } from 'instantsearch.js/es/widgets';
See code examples
See live example

About this widget

Use the hits widget to display a list of results.

To configure the number of hits to show, use the hitsPerPage widget or the configure widget.

For guidance on how to search across more than one index, read the multi-index search guide.

If there are no hits, you should display a message to users and clear filters so they can start over.

Examples

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

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

Options

Parameter Description
container
type: string|HTMLElement
Required

The CSS Selector or HTMLElement to insert the widget into.
Copy 
1
2
3

hits({
  container: '#hits',
});
escapeHTML
type: boolean
default: true
Optional

Escapes HTML entities from hits string values.
Copy 
1
2
3
4

hits({
  // ...
  escapeHTML: false,
});
templates
type: object
Optional

The templates to use for the widget.
Copy 
1
2
3
4
5
6

hits({
  // ...
  templates: {
    // ...
  },
});
cssClasses
type: object
default: {}
Optional

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.
Copy 
1
2
3
4
5
6
7

hits({
  // ...
  cssClasses: {
    root: 'MyCustomHits',
    list: ['MyCustomHitsList', 'MyCustomHitsList--subclass'],
  },
});
transformItems
type: function
default: items => items
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 transformItems to remove items since this will affect your pagination.

The entire results data is also available, including all regular response parameters and helper parameters (for example, disjunctiveFacetsRefinements).

If you’re transforming an attribute with the highlight widget, you must 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

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 the widget’s UI using the Templates API.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.

The html function is available starting from v4.46.0.

Parameter Description
empty
type: string|function
Optional

The template to use when there are no results. It exposes the results object.
Copy 
1
2
3
4
5
6
7
8

hits({
  // ...
  templates: {
    empty(results, { html }) {
      return html`No results for <q>${results.query}</q>`;
    },
  },
});
item
type: string|function
Optional

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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

HTML output

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

<div class="ais-Hits">
  <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.

Copy 
1

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

Then it’s a 3-step process:

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

See code examples

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

const renderHits = (renderOptions, isFirstRender) => {
  const {
    object[] hits,
    object results,
    function sendEvent,
    object widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
}

Rendering options

Parameter Description
hits
type: 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.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

  document.querySelector('#hits').innerHTML = `
    <ul>
      ${hits
        .map(
          item =>
            `<li>
              ${instantsearch.highlight({ attribute: 'name', hit: item })}
            </li>`
        )
        .join('')}
    </ul>
  `;
};
results
type: 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 hits instead. You should also consider the stats widget if you want to build a widget that displays metadata about the search.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

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>
  `;
};
sendEvent
type: (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

Learn more about these events in the insights middleware documentation.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

// 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',
  }
*/
widgetParams
type: object

All original widget options forwarded to the render function.
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13

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

  widgetParams.container.innerHTML = '...';
};

// ...

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

Create and instantiate the custom widget

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

  • Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
  • Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customHits = connectHits(
  renderHits
);

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

Instance options

Parameter Description
escapeHTML
type: boolean
default: true
Optional

Escapes HTML entities from hits string values.
Copy 
1
2
3

customHits({
  escapeHTML: false,
});
transformItems
type: function
default: items => items
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 transformItems to remove items since this will affect your pagination.

The entire results data is also available, including all regular response parameters and helper parameters (for example, disjunctiveFacetsRefinements).

If you’re transforming an attribute with the highlight widget, you must transform item._highlightResult[attribute].value.

‘function’: |

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

  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

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
25
26
27

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

  widgetParams.container.innerHTML = `
    <ul>
      ${hits
        .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.

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, use the sendEvent function in your item template and send a custom click event.

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

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.

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
25
26
27
28
29
30
31
32
33
34
35
36
37
38

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 this item 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.

Guide Send click and conversion events with InstantSearch.js
Did you find this page helpful?
InstantSearch.js v4