Intermediate
How to track custom events on Hotjar
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.
Prerequisites
- Active Hotjar account with tracking code installed
- Basic JavaScript knowledge
- Website administrator access
- Hotjar tracking script properly implemented on your site
1
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.
Tip
Make sure you're in the correct site if you manage multiple websites
2
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.
Tip
Use CSS Selector for button clicks, form submissions, and link clicks
3
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.Tip
Use browser developer tools to find the exact CSS selector for your elements
4
Implement API Events with JavaScript
For API Events, add this JavaScript code to your website:
Replace
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.Tip
Always use consistent naming conventions for your events
5
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.
Tip
Use URL filters to avoid tracking the same event across unrelated pages
6
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.
Tip
Events may take a few minutes to appear in your dashboard
7
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.
Tip
Combine page views and custom events to create comprehensive conversion funnels
8
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.
Tip
Use the date filter to analyze event performance over specific time periods
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.
Ready to get started with Hotjar?
Put this tutorial into practice. Visit Hotjar and follow the steps above.
Visit Hotjar →