Skip to main content
This page shows how to send custom click and conversion events from an InstantSearch app. For the concepts behind event tracking, see Click and conversion events. For other implementation paths, see Choose how to send events.

​
Enable events collection

To follow this guide, build search results or category pages with one of these UI libraries: InstantSearch loads the search-insights library for you from jsDelivr. You don’t need to install or initialize it yourself. If you’re using a Content Security Policy and you want to let InstantSearch load search-insights, add https://cdn.jsdelivr.net to your list of trusted JavaScript sources. 
script-src https://cdn.jsdelivr.net/
If you prefer self-hosting search-insights, add it to your project:
  1. Install the Insights client
  2. Initialize the Insights client (optional)
InstantSearch doesn’t load search-insights when it detects it on the page. You can enable automatic collection in the Algolia dashboard or in your InstantSearch app. Enabling automatic events collection does the following: Go to the Events hub in the Algolia dashboard to check the default events arriving from your website or app. For more information, see Validate your events.

​
No code

  1. Go to the Algolia dashboard and select your Algolia .
  2. On the left sidebar, select Data sources > Events > Settings.
  3. Click Enable automatic events collection.

​
Code

Enable the insights option: 
const search = instantsearch({
  searchClient,
  indexName: "YourIndexName",
  insights: true, 
});
// Add your InstantSearch widgets here
search.start();
For more on tracking queryID and userToken, see Keep track of query IDs and User token.

​
Decide which custom events to send

InstantSearch automatically captures many events through its widgets. Add custom events when an interaction matters to your business but isn’t covered by a default widget event. For example, a user might be presented with a list of real estate properties after performing a search from your homepage. Then click a property to view more details. Finally, convert by contacting the realtor. In this example, track these events:
  • Property Clicked by using the clickedObjectIDsAfterSearch method.
  • Property Contacted by using the convertedObjectIDsAfterSearch method.
A conversion is any user action that’s valuable to your business; a user purchasing from your store or subscribing to your newsletter are examples of common conversions. — GA4 About conversions

​
Track query IDs across pages

Conversion events often happen outside the search results page.
  • A query ID is returned by the when a user performs a search.
  • To associate a conversion with the correct , save this query ID and include it in your conversion events.
  • To link conversion events back to the originating search request on your search results or category pages, track query IDs across your pages.

​
Track conversion events

​
Send events from InstantSearch widgets

You can use the sendEvent function to send conversion events from your InstantSearch app. 
hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <h2>${components.Highlight({ attribute: "name", hit })}</h2>
        <p>${hit.description}</p>
        <button
          onClick="${() =>
            sendEvent("conversion", hit, "Item Added To Favorites");
          }"
        >
          Add to favorites
        </button>
      `;
    },
  },
});
Unlike click events, setting custom conversion events doesn’t prevent the custom click event from being sent.

​
On pages without InstantSearch widgets

Conversion events represent user actions that are important to the success of your business. For example:
JavaScript
// A user reached the bottom of an article page
window.aa("convertedObjectIDsAfterSearch", {
  eventName: "Article Read",
  index: "YourIndexName",
  queryID: "query-1",
  objectIDs: ["objectID-1"],
});
The window.aa object is the API client for the Insights API and is globally available if you enabled automatic events collection. The queryID parameter is used by Algolia to relate the event to a prior search. If the event isn’t directly related to a search, for example, it’s triggered on the homepage, use the convertedObjectIDs method instead.
JavaScript
// A user watched a video
window.aa("convertedObjectIDs", {
  eventName: "Video watched",
  index: "YourIndexName",
  objectIDs: ["objectID-1"],
});

​
Track click events

​
Override default click events

The hits and infiniteHits widgets expose a sendEvent function. Use it to send click events when users interact with your search results. 
hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <div onClick="${() => sendEvent("click", hit, "Item Clicked")}">
          <h2>${components.Highlight({ attribute: "name", hit })}</h2>
          <p>${hit.description}</p>
        </div>
      `;
    },
  },
});
You can set more events on specific parts of your template. In the following example, when users click the View more info button, two events are sent to the Insights API:
  • A click event with the eventName “Item More Info Clicked”.
  • A click event with the eventName “Item Clicked” (through event propagation).
hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <div onClick="${() => sendEvent("click", hit, "Item Clicked")}">
          <h2>${components.Highlight({ attribute: "name", hit })}</h2>
          <p>${hit.description}</p>
          <button
            onClick="${() => sendEvent("click", hit, "Item More Info Clicked")}"
          >
            View more info
          </button>
        </div>
      `;
    },
  },
});
To only send the most specific event per clicked element, you can use Event.stopPropagation in your event handler. 
hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <div onClick="${() => sendEvent("click", hit, "Item Clicked")}">
          <!-- ... -->
          <button
            onClick="${(event) => {
              event.stopPropagation(); 

              sendEvent("click", hit, "Item More Info Clicked");
            }}"
          >
            View more info
          </button>
        </div>
      `;
    },
  },
});
When InstantSearch captures a custom click event that you defined, it doesn’t send the default click event. In the following example, when users click the View more info button, only the “Item More Info Clicked” event is sent. 
hits({
  templates: {
    item(hit, { html, components, sendEvent }) {
      return html`
        <h2>${components.Highlight({ attribute: "name", hit })}</h2>
        <p>${hit.description}</p>
        <button
          onClick="${() => sendEvent("click", hit, "Item More Info Clicked")}"
        >
          View more info
        </button>
      `;
    },
  },
});

​
Track more click events

For Algolia Recommend and Personalization, capture additional click events when users select individual items:
  • On your home page
  • From recommendations
To send click events with the Insights client, add the following code whenever a user clicks on an item—for example, on your homepage.
JavaScript
window.aa("clickedObjectIDs", {
  index: "YourIndexName",
  eventName: "Item Clicked",
  objectIDs: ["objectID-1"],
});

​
Optional: identify known users for Personalization

For effective personalization, identify users across sessions. It’s best to use an identifier from your authentication system after users sign in. After getting the identifier from your system, set it as the authenticatedUserToken parameter.
JavaScript
// Get a unique, pseudonymous identifier for signed-in users
const authenticatedUserToken = getUserTokenAfterSignIn();
window.aa("setAuthenticatedUserToken", authenticatedUserToken);
If you can’t get persistent user identifiers from your system, you can store the anonymous user token in a cookie after obtaining user consent.
JavaScript
// If user consented
aa("init", {
  partial: true,
  useCookie: true,
});
If you don’t use persistent user identifiers, a new anonymous user token is generated on every page refresh. For more on identity strategy and persistence, see User token. InstantSearch automatically sends view events for search results and category pages. Send additional view events for experiences outside InstantSearch widgets, such as your homepage or recommendation modules.

​
Optional: send view events for Personalization

Personalization benefits from the same click and conversion events, plus it can use view events to enrich each . Use the following code snippet to track view events, such as when a user views search results.
JavaScript
window.aa("viewedObjectIDs", {
  index: "YourIndexName",
  eventName: "Item Viewed",
  objectIDs: ["objectID-1"],
});
You don’t need to send a queryID when tracking view events.

​
Examples

​
Add events to a React InstantSearch application

Last modified on April 22, 2026