How to Implement Hotjar Custom Event Tracking: A Step‑by‑Step Guide

Understanding exactly how visitors interact with your site is the key to conversion optimization. While Heatmaps and Recordings give you a visual overview, custom event tracking unlocks granular, action‑specific data that standard Hotjar tools can’t capture. In this guide we’ll walk you through everything you need to know—why it matters, how to set it up, and best‑practice tips for beginners to intermediate users.

Why Use Custom Events in Hotjar?

• Targeted insights: Track clicks, form submissions, video plays, or any JavaScript‑triggered interaction.
• Combine with Heatmaps: See exactly where high‑value actions happen on a page.
• Improve CRO testing: Validate hypotheses by measuring event frequency before and after changes.
• Segment recordings: Filter recordings by specific events to watch only the most relevant sessions.

Prerequisites

Before you begin, make sure you have:

1. A Hotjar account with the Tracking Code installed on every page.
2. Access to the website’s JavaScript (CMS, theme, or a tag manager).
3. Clear definitions of the events you want to capture (e.g., "Add to Cart", "Download PDF").

Step 1: Identify the Event and Its Selector

Open the page you want to track and use your browser’s DevTools to locate the element. You’ll need either a CSS selector or a JavaScript reference.

// Example: a button with class .cta-download const downloadBtn = document.querySelector('.cta-download');

Step 2: Add the Hotjar Event Call

Hotjar provides the hj() function. Use the event method to fire a custom event whenever the user interacts with the element.

downloadBtn.addEventListener('click', function() {     // Send custom event to Hotjar     hj('event', 'download_pdf'); });

Replace 'download_pdf' with a descriptive name that matches your event list.

Step 3: Verify the Event in Hotjar

After implementing the code, open Hotjar → Events. You should see the newly created event appear within a few minutes. Click the event name to view a breakdown of triggers, unique users, and the pages where it fired.

Step 4: Use Events in Recordings & Funnels

Once Hotjar registers the event, you can:

• Filter recordings: Go to Recordings → Filters → Event is and select your event.
• Create Funnels: In Funnels → Add Funnel Step, choose Event and pick your custom event to measure conversion rates.

Advanced Tips

Send Event Data with Additional Context

You can attach extra information (e.g., product ID, user segment) by using the second argument of hj('event') as an object.

hj('event', 'add_to_cart', {     product_id: 'SKU12345',     price: 49.99,     user_type: 'returning' });

Hotjar will store these key/value pairs, allowing you to segment events later.

Leverage Google Tag Manager (GTM)

If you prefer not to edit site code directly, you can fire the Hotjar event via GTM:

1. Create a Custom HTML Tag with the hj('event', ...) snippet.
2. Set a trigger based on clicks, form submissions, or DOM Ready.
3. Publish the container and test with GTM’s preview mode.

Combine with Hotjar Surveys

Trigger a survey right after a specific event, such as a failed checkout, to collect immediate feedback. In the Survey builder, choose Show after event and select your custom event.

Common Pitfalls & How to Avoid Them

• Duplicate events: Ensure the listener isn’t attached multiple times (e.g., inside a function that runs on every AJAX load).
• Incorrect selector: Test the selector in the console before deploying.
• Event name mismatch: Hotjar treats event names as case‑sensitive; keep naming consistent.
• Missing Hotjar script: Verify the hj function exists before calling it.

  if (typeof hj === 'function') { hj('event','my_event'); }

Conclusion

Custom event tracking turns Hotjar from a visual analytics tool into a precise, action‑oriented platform. By defining key interactions, firing hj('event') calls, and leveraging recordings, funnels, and surveys, you gain the data needed to optimize user experience and boost conversions.

FAQ

Do I need a paid Hotjar plan for custom events?

Custom events are available on the Free plan, but higher event limits and advanced reporting require a Plus or Business plan.

Can I track events on Single‑Page Applications (SPAs)?

Yes—attach the event listener after each route change or use Hotjar’s hj('stateChange') method to ensure the script re‑initializes.

Will custom events affect page load speed?

The hj('event') call is asynchronous and adds negligible overhead. Keep the code lightweight and avoid heavy calculations inside the event handler.

How many custom events can I create?

Hotjar allows up to 500 distinct event names per site on paid plans; the free tier caps at 50.

Take Action Now

Start by listing the top three user actions you want to measure. Implement the snippets, verify in Hotjar, and watch your insights grow. Need help customizing events for a complex site? Contact our CRO team for a free audit.