In this article, we'll explain the settings and features related to iframes, and the limitations that persist when using Hotjar with pages that contain iframes.
- What is the default behavior when Hotjar detects an iframe?
- What does it mean to allow iframes within Hotjar?
- What limitations exist after allowing an iframe?
What is the default behavior when Hotjar detects an iframe?
By default, Heatmaps and Recordings will block iframe content. Instead of the iframe content, you'll see a message stating that Hotjar cannot track iframes embedded on your page:
If you're unfamiliar with iframes, you can think of them as web pages inside other web pages. They are often used to add tools or content from a third-party website, such as chatbots, videos, or forms. You can learn more about iframes in the Mozilla Developer Network documentation.
What does it mean to allow iframes within Hotjar?
Before allowing iframes on your Hotjar Site, review the next section in this article that outlines the limitations that may prevent iframes from being displayed in Hotjar.
How to allow an iframe within Hotjar:
Add data-hj-allow-iframe as an HTML attribute to your iframe.
<iframe src="https://example.com/page.html" data-hj-allow-iframe=""></iframe>
This can be written as data-hj-allow-iframe="", data-hj-allow-iframe="true", or just data-hj-allow-iframe. Either way, the value will show as "true" on the backend.
This attribute must be placed in the <iframe> element itself and cannot be placed in the parent element of the iframe. Many third-party tools do not allow you to edit their <iframe> elements, which means they cannot be allowed.
An iframe source page will reload each time it's displayed within Hotjar
The URL that the iframe points to is stored on our servers and reloaded every time a recording is played. This means that if loading the iframe source page would trigger some additional behavior, this could cause unexpected and adverse results.
Visit your Sites & Organizations page.
Click on the site settings gear icon to visit your site settings page.
Expand the Session targeting & tracking menu.
Enter the top-level domain name you wish to allow, under the heading ALLOWED IFRAME DOMAINS.
Only enter the top-level domain when entering domain names into the ALLOWED IFRAME DOMAINS field. The top-level domain is the domain without www, http://, or https:// connected to it. For example, if you wanted to allow https://www.hotjar.com/ to this field, the top-level domain would be hotjar.com
What limitations exist after allowing an iframe?
Before allowing an iframe, consider the limitations that will persist even after allowing the iframe:
❌ Hotjar cannot allow an iframe if its src attribute uses a relative page path (Example: src=“/page”) instead of the complete URL (Example: src=“https://hotjar.com/page”).
❌ Interactions (click and scroll events, typing, CSS animations, DOM mutations, etc.) will not be tracked in the iframe.
- Third-party video players (including YouTube and Vimeo)
- Third-party forms (including Typeform forms)
- Web-apps that are loaded via iframes
- Most third-party payment systems
- Most third-party content
This means that Hotjar can only show the following aspects of an allowed iframe:
✅ Cursor behavior is tracked, relative to the parent page.
Workaround for same-source iframes
If you can edit the HTML of your iframe element, and your iframe source URL uses the same domain as the page the iframe is being added to, then you can place the Hotjar Tracking Code inside the iframe source page, instead of the parent page. With this option, you can track the iframe source page but not other aspects of the parent page.