How to track custom events on Hotjar

intermediate 8 min read Updated 2026-03-18

Quick Answer

Track custom events in Hotjar by adding JavaScript event triggers to your website code or using CSS selectors to define specific user interactions. You can then view these events in your Hotjar dashboard under Events or create funnels based on custom event data.

Try Hotjar Full Hotjar Review

Prerequisites

Active Hotjar account with tracking code installed
Basic JavaScript knowledge
Website administrator access
Hotjar tracking script properly implemented on your site

Step-by-Step Instructions

Access Events in your Hotjar dashboard

Log into your Hotjar account and navigate to Events in the left sidebar. Click + New Event to create your first custom event tracking setup.

Make sure you're in the correct site if you manage multiple websites

Choose your event tracking method

Select between CSS Selector for click-based events or API Event for JavaScript-triggered events. CSS Selector is easier for beginners, while API Events offer more flexibility for complex interactions.

Use CSS Selector for button clicks, form submissions, and link clicks

Configure CSS Selector events

If using CSS Selector, enter the CSS selector for your target element (e.g., #signup-button or .cta-link). Name your event descriptively like Header CTA Click or Newsletter Signup. Click Verify Selector to test it works correctly.

Use browser developer tools to find the exact CSS selector for your elements

Implement API Events with JavaScript

For API Events, add this JavaScript code to your website:

hj('event', 'event_name');

Replace event_name with your custom event name. Place this code where the event should trigger, such as in a button click handler or form submission function.

Always use consistent naming conventions for your events

Add event parameters and conditions

Click Advanced Options to set additional parameters like page URL filters, user segments, or device types. You can limit events to specific pages using Page URL contains or Page URL matches conditions.

Use URL filters to avoid tracking the same event across unrelated pages

Test your custom event

Click Save & Start Tracking to activate your event. Visit your website and perform the tracked action. Return to Hotjar and check the Events dashboard to verify your event is being recorded correctly.

Events may take a few minutes to appear in your dashboard

Create funnels with custom events

Navigate to Funnels in your Hotjar dashboard and click + New Funnel. Add your custom events as funnel steps by selecting Event and choosing your custom event from the dropdown menu.

Combine page views and custom events to create comprehensive conversion funnels

Analyze event data and insights

View your custom event data in the Events section, where you can see trigger counts, conversion rates, and user recordings. Click on any event to see associated heatmaps and session recordings for deeper analysis.

Use the date filter to analyze event performance over specific time periods

Common Issues & Troubleshooting

Events not showing in dashboard

Check that your CSS selector is correct using browser developer tools. Verify the Hotjar tracking code is properly installed and events may take up to 30 minutes to appear.

API events not triggering

Ensure the hj('event', 'event_name') code is placed after the Hotjar tracking script loads. Check browser console for JavaScript errors that might prevent execution.

Too many false positive events

Refine your CSS selectors to be more specific. Add page URL conditions in Advanced Options to limit where events are tracked.

Events working on some pages but not others

Verify that your CSS selectors exist on all target pages. For API events, ensure the JavaScript code is included on all relevant pages or use a tag manager for consistent deployment.

Prices mentioned in this guide are pulled from current plan data and may change. Always verify on the official Hotjar website before purchasing.

Visit Hotjar View Hotjar Pricing