iframe restrictions
Due to potential security problems inherent to how iframes work, Hotjar cannot track user interactions within iframes. However, Hotjar can still display iframes, as long as the iframe does not rely on JavaScript to render its content. Hotjar refers display iframes in this way as "allowing" iframes.
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?
Hotjar offers the ability to allow iframes to appear inside heatmaps and recordings. However, this does not mean Hotjar can track user interactions within the iframes. It only means that you can load the iframe page content. If JavaScript is required for the iframe content to load, allowing the iframe will not work because Hotjar will prevent the JavaScript from loading.
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.
You can do this by adding an HTML attribute, data-hj-allow-iframe, to the iframe you wish to display.
<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:
❌ The iframe must have a src attribute.
❌ 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”).
❌ JavaScript will be blocked within the iframe.
❌ Interactions (click and scroll events, typing, CSS animations, DOM mutations, etc.) will not be tracked in the iframe.
These limitations mean that many third-party iframes may not display because they rely on JavaScript, even after allowing the iframe. Some examples of content types that won't work with an allowed iframe include:
- Chatbots
- 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:
✅ Static page content (without JavaScript) loading through an 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.