Hotjar JavaScript Functions Reference

Installing the Hotjar Tracking Code on your site allows Hotjar to collect behavioral data about how users interact with your site through analytics, and through learning about users through feedback tools. 

The Hotjar script offers a range of JavaScript functions that allow you to target specific data to be collected.

Using the hj() Object

By placing the Hotjar tracking code on your site, the hj object becomes globally accessible by scripts on your pages. This allows you to pass in the name of the function or API to Hotjar that you want to access as the first argument to a call to hj().

For example, you can send events to Hotjar by calling hj('event', ['example_action']).

The hj() object gives you access to Hotjar APIs, as well as other functions that pass data to Hotjar, offer more fine-grained control over how tools are targeted or track data. The functions are: 

• 'stateChange'
• 'event'

'stateChange'

stateChange is used exclusively when your site has been developed as a single page web app (SPA) where page changes are not reflected in the URL toolbar. A manual set up of what Hotjar reads as a page change is needed.

hj('stateChange', relativePath);

The relative path should take a form such as 'some/relative/path'. For example, 'product/red-trainer'.

For a thorough walkthrough of this setup, read the detailed guide to URL change settings.

Back to top

'event'

For Observe tools (Heatmaps and Recordings), 'event' is available on the Observe Plus, Observe Business, or Observe Scale plans. You can use 'event' with our Ask tools (Feedback and Surveys) when your site is on the Ask Plus, Ask Business, or Ask Scale plan.

With Recordings, it may be useful to automatically add events to sessions based on specific actions. For example, you might want to add an event to a Recording every time someone clicked on a call to action (CTA) button.

Once an event is passed to Hotjar, the current user’s session will store the event with their session recording, allowing you to Filter and Segment Recordings by events present (or not) in the Recording.

hj('event', arrayOfStrings);

Example:

Often, it’s useful to track users who’ve clicked on a CTA button with an event. Perhaps you’re interested in diagnosing why people are not clicking on it. By passing the following event, you can filter your recordings by those who have not clicked on your call to action:

document.querySelector('#my-button')
	.addEventListener('click', () => hj('event', ['clicked_cta']));

Back to top