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 tools and triggering feedback widgets. 

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, triggering analytics reports or feedback tools is done through calling hj('trigger', ['trigger-name']).

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

• 'formSubmitSuccessful' & 'formSubmitFailed'
• 'stateChange'
• 'tagRecording'
• 'trigger'
• 'vpv' (Virtual Page View)

---

'formSubmitSuccessful' & 'formSubmitFailed'

These functions are used exclusively with Forms reports. Hotjar does its best to detect successful form submission with Form reports, but especially when a form submission happens using AJAX, it can need a little extra help. This tells Hotjar that a form has been successfully submitted. This script should be placed inside the event handler for your form submission.

You have two options here: ‘formSubmitSuccessful’ and ‘formSubmitFailed’.

The most basic use of these functions would be a conditional statement checking against your site's form validation.

document.querySelector('#myform').addEventListener("submit", () => {
    "use strict";
    event.preventDefault();
  
    /* ..Your validation code.. */

    if (valid) {

        /* Validation passed - continue... */
        hj('formSubmitSuccessful');

    } else {
		
        /* Validation not passed - halt */
        hj('formSubmitFailed');

    }

    return false;
});

Back to top

'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

'tagRecording' (only available on Plus and Business plans)

With Recordings, it may be useful to automatically tag sessions with information. For example, you might want to tag a Recording every time someone clicked on a call to action (CTA) button.

Once a tag is passed to Hotjar, the current visitor’s session will be tagged with a Recording, allowing you to Filter and Segment Recordings by tags present (or not) in the Recording.

hj('tagRecording', arrayOfStrings);

Example:

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

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

Back to top

'trigger' (available on Plus and Business Plans)

Triggers tell Hotjar to activate a specific tool when it is activated. The following tools can be triggered:

• Heatmaps
• Recordings
• Incoming Feedback and Surveys

hj('trigger', 'name_of_trigger');

Example:

Let’s say you only wanted to start Recording someone who has clicked on your CTA button. The code added to your site would be: 

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

Back to top

'vpv' (Virtual Page View)

A virtual page view (vpv) can be sent to Hotjar to add virtual steps to your Hotjar Funnel. This is useful when your Funnel has a step that doesn't have a URL change.

For more information, check out How to Track Funnel Steps if My URL Doesn't Change?

hj('vpv', 'funnel-step');

Example:

A key stage in your Funnel may be whether or not someone has signed up for a newsletter, but by doing so the page never changes. Your Funnel might have the following steps:

1. Landing Page: /my-awesome-landing-page
2. Newsletter Signup (Virtual Page View): signed_up

This would require the following code:

document.querySelector('#my-button')
	.addEventListener('submit', () => hj('vpv', 'signed_up'));

Back to top