---
title: Heatmaps
description: >-
  Heatmaps are a type of visualization showing where users click on your
  website.
breadcrumbs: Docs > Session Replay > Heatmaps
---

# Heatmaps

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-landing.a76b3de1c770e1ba2a29c6aa14a5ed54.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-landing.a76b3de1c770e1ba2a29c6aa14a5ed54.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="An overview of the heatmap functionality." /%}

A heatmap (or heat map) is a visualization of your user's interactions overlaid on Session Replay data. There are three different types of heatmaps:

- **Click maps:** View user interactions (clicks) to understand how users engage with your page.
- **Top Elements:** View a ranking of up to the top 10 most interacted-with elements on a given page.
- **Scroll maps:** View how far users scroll down a page, including where the average fold of a page falls. The average fold is the lowest point on a page that a user can see on their device without scrolling.

Use heatmaps to review complex data at a glance and gain insights around optimizing your user experience.

## Prerequisites{% #prerequisites %}

To get started with heatmaps:

1. Verify your SDK version:
   - For Click maps, you must be on the latest version of the SDK (v4.40.0 or later).
   - For Scroll maps, you must be on (v4.50.0 or later).
1. Enable [Session Replay](https://docs.datadoghq.com/session_replay.md).
1. Set`trackUserInteractions: true` in the SDK initialization to enable action tracking (required for Clickmaps).

## Getting started{% #getting-started %}

{% tab title="RUM" %}
Navigate to [**Digital Experience > Real User Monitoring > Session Replay > Heatmaps**](https://app.datadoghq.com/rum/heatmap/). Select your application and view.

On the [Real User Monitoring landing page](https://app.datadoghq.com/rum/performance-monitoring), select your application from the application selector and view. To the left of the timeframe selector, you can select the type of heatmap you would like to view: Top elements, Click map, or Scroll map.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-different-views.c502a102ca6678998bd9d0f994edc176.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-different-views.c502a102ca6678998bd9d0f994edc176.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The heatmaps page has multiple ways to show different views: by application, map type, device type, action name, and granular filters." /%}

{% /tab %}

{% tab title="Product Analytics" %}
Navigate to [**Digital Experience > Product Analytics > Heatmaps**](https://app.datadoghq.com/product-analytics/heatmap). Select your application and view.

From this page, you can select the type of heatmap (Top elements, Click map, Scroll map) you would like to see for a particular view.

{% image
   source="https://docs.dd-static.net/images/product_analytics/heatmaps/pa-heatmaps-page.e97071561f16fd6ac720e9ad2574b911.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/product_analytics/heatmaps/pa-heatmaps-page.e97071561f16fd6ac720e9ad2574b911.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="For each view, you can select a different type of heatmap: Top Elements, Click Map, or Scroll Map." /%}

Click on a view name for a more detailed look at the related heatmap.

{% image
   source="https://docs.dd-static.net/images/product_analytics/heatmaps/pa-heatmaps-annotated.4a8a6df89f103b2e8f891f4173e1082b.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/product_analytics/heatmaps/pa-heatmaps-annotated.4a8a6df89f103b2e8f891f4173e1082b.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The heatmaps page has multiple ways to show different views: by application, map type, device type, action name, and granular filters." /%}

{% /tab %}

You have the following additional view options:

- To switch the view being shown, use the **View Name** and **Application** selectors at the top.
- To change the device view, use the **Device type** selector.
- To filter by action name, use the **Filter actions by** dropdown.
- To add more granular filters, like a specific geography for example, click the **Add Filter** button.

## Top Elements{% #top-elements %}

Top Elements heatmaps aggregate click actions on a given view by displaying the elements that are most interacted with, in addition to their interaction rank. The ranking on the map itself corresponds to the action name on the side.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-top-elements.dcc0be2d5a77539594e747c800b5849e.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-top-elements.dcc0be2d5a77539594e747c800b5849e.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="A ranking of the top elements clicked on a page." /%}

Hover over any action name in the panel to highlight the corresponding action on the map.

## Click maps{% #click-maps %}

A Click map shows you the actions most interacted with on a given view by aggregating user click actions from sessions and visualizing them as blobs on the map.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-clickmaps.09b33456d5be522f3ff86e21b58196b7.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-clickmaps.09b33456d5be522f3ff86e21b58196b7.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Clickmap data overlayed on a website." /%}

On the left is a list of all actions that occurred on the page, listed by frequency. When you click into an action, you can understand more about that interaction, for example:

- The number of times the user performed the action and where it falls in overall analytics of top actions on a given page.
- If that action had a frustration signal occurring on it (for example, if a user rage clicked on that button), you can view the associated frustration signals as well.

From this view, you can also click the **Start a Funnel** button to identify user drop off.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-clickmap-actions.07e1a1c17fc5b45756054e15620b7afd.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-clickmap-actions.07e1a1c17fc5b45756054e15620b7afd.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Shows an example action and the information you can get about that action." /%}

## Scroll maps{% #scroll-maps %}

Scroll maps display the aggregate scroll activity on a given page. Use Scroll maps to see where the average fold of the page falls, and how many users scroll to a given depth. You can drag the floating blue bar on a Scroll map to the depth you wish to assess.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-scrollmap.f430ba17afe9585eea8653c6043c69a7.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-scrollmap.f430ba17afe9585eea8653c6043c69a7.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Scrollmap of the bedding page in a sample ecommerce application" /%}

The panel to the left of the Scroll map provides high-level insights with direct links to query results, such as a link to a list of views where the user scrolled past a given percentile. Below the insight panel is a minimap of the page and a distribution graph displaying granular scroll data, useful for identifying where the biggest drop-off occurs.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-minimap.9837cbb5b5422df8ebf60b89caf3ceb4.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-minimap.9837cbb5b5422df8ebf60b89caf3ceb4.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="A screenshot of the queries for scroll data insights" /%}

## Screenshots{% #screenshots %}

A screenshot is the state of a view at a particular point in time. Changing the screenshot shows different results, depending on the screenshot selected. You can also save screenshots so that everyone in your organization can analyze the same view state.

### Changing screenshots{% #changing-screenshots %}

From the heatmap view, click the **Change Screenshot** button. A dropdown appears with three options.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-change-screenshot-button.07b1fadbde7a9a22ec2e0092dd1fe8e1.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-change-screenshot-button.07b1fadbde7a9a22ec2e0092dd1fe8e1.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="The Change Screenshot dropdown showing three options: Existing screenshots, Take new screenshot, and Grab from replay." /%}

**Existing screenshots**

Choose from screenshots previously saved by you or your teammates. This helps ensure everyone in your organization analyzes the same view state.

**Take new screenshot**

Capture a screenshot directly from your live application. Use this option when the state you need—such as an open modal, a hover menu, or a specific scroll position—does not exist in your recorded replays.

**Prerequisite**: Install the [Datadog Test Recorder](https://chromewebstore.google.com/detail/datadog-test-recorder/kkbncfpddhdmkfmalecgnphegacgejoa) Chrome extension before using this option. The extension loads your live application in an embedded browser within Datadog, letting you navigate to the exact page and UI state you want to capture.

1. Click **Take new screenshot**.

1. Navigate to the page you want to capture in the embedded browser.

1. Scroll and interact with the page to display the content you want.

1. Select a masking level to prevent sensitive data from appearing in your heatmap screenshot. Individual element-level privacy settings configured in your code still take precedence. For more information, see [Privacy options](https://docs.datadoghq.com/session_replay/browser/privacy_options.md#privacy-options).

   {% image
      source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-take-new-screenshot.2804350a88f56d9f17a9cdaef7e77572.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-take-new-screenshot.2804350a88f56d9f17a9cdaef7e77572.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="The Take new screenshot panel showing navigation instructions and a masking level selector." /%}

1. Click **Take Screenshot**. A preview of the screenshot opens.

1. Review the preview and click **Confirm** to apply the screenshot to your heatmap.

**Grab from replay**

Select a screenshot from a recorded Session Replay.

1. Click **Grab from replay**.

   {% image
      source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-grab-from-replay-selected.0291946caa1822a856e838bb8ccd6600.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-grab-from-replay-selected.0291946caa1822a856e838bb8ccd6600.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="The Change Screenshot dropdown with Grab from replay selected." /%}

1. Click an action event on the right to select a different snapshot for your heatmap.

   {% image
      source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-list-all-events-1.cff4b03b6a2bb89d8921c48fb1c54e67.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-list-all-events-1.cff4b03b6a2bb89d8921c48fb1c54e67.png?auto=format&fit=max&w=850&dpr=2 2x"
      alt="List of action events for the session replay." /%}

1. If the session does not contain the action that leads to the desired screenshot, return to the list of replays by clicking **Choose Another Replay**.

1. Click **Take Screenshot** to apply the screenshot at the paused point to the heatmap.

### Saving screenshots{% #saving-screenshots %}

Screenshots taken using **Grab from replay** or **Take new screenshot** are automatically saved and become the default view for anyone in your organization who opens the heatmap. To also save the screenshot auto-picked from a recent replay, click **Save** on the current screenshot.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-save-screenshot-1.f4232c2bdfaa3b44e1d646751d459142.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-save-screenshot-1.f4232c2bdfaa3b44e1d646751d459142.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Click Save to apply the auto-picked screenshot." /%}

You can save multiple screenshots for the same view (for example: default view, open navigation menu, open modal) and switch between screenshots saved by teammates.

To remove the currently saved screenshot and revert to an auto-picked one from a recent replay, click **Unpin** on the current screenshot.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-unpin-screenshot-1.b15d06ce8c103c3b32d010317d28828c.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-unpin-screenshot-1.b15d06ce8c103c3b32d010317d28828c.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Click unpin to remove the currently pinned screenshot." /%}

## Data retention{% #data-retention %}

The time periods you can view in a heatmap depend on where you access it:

- **RUM**: Session Replay heatmaps use RUM click data (RUM action events), which has a 30-day retention period.
- **Product Analytics**: Heatmaps use Product Analytics click data, which has a 15-month retention period.

## Next steps{% #next-steps %}

After analyzing heatmaps, the next step is to understand the user action by exploring related data. Watch associated [session replays](https://docs.datadoghq.com/session_replay.md) to see user actions in the context of their overall session, or navigate to an Analytics explorer in [RUM](https://docs.datadoghq.com/real_user_monitoring/explorer.md) or [Product Analytics](https://docs.datadoghq.com/product_analytics/charts/analytics_explorer.md) to analyze your user data.

## Troubleshooting{% #troubleshooting %}

### I am looking at a heatmap for a given view, but it's showing me an unexpected page.{% #i-am-looking-at-a-heatmap-for-a-given-view-but-its-showing-me-an-unexpected-page %}

Heatmaps are based on view names. Depending on how your application is configured, many pages can start being grouped under the same view name, or you can start having specific view names.

### The view that I selected is not showing the initial content.{% #the-view-that-i-selected-is-not-showing-the-initial-content %}

Heatmaps are generated with Session Replay data. Datadog's intelligent algorithm picks a replay that is both recent and best matches the initial state of the page. In some cases, this replay might not be the one you want to use. To switch the snapshot of your heatmap, use the **Change Snapshot** button to navigate through the different states of a replay and find the one you want. If the replay you're viewing does not have the snapshot you're looking for, you can use the **Choose Another Replay** button to select another replay of the same view.

{% video
   url="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-change-the-snapshot.mp4" /%}

### On the action list on the side of my heatmap, I see an icon showing an element that is not visible in the heatmap.{% #on-the-action-list-on-the-side-of-my-heatmap-i-see-an-icon-showing-an-element-that-is-not-visible-in-the-heatmap %}

The tooltip on the icon says element is not visible. This means that the element is a common action on your page, but it's not displayed on the snapshot in the heatmap. To see that element, you can click **Change Snapshot** in the top right corner to switch the snapshot of your heatmap to one where that element is present.

{% image
   source="https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-hidden-elements.f4a0c1a43cc1d8c287592710abe0889e.png?auto=format&fit=max&w=850 1x, https://docs.dd-static.net/images/real_user_monitoring/session_replay/heatmaps/heatmaps-hidden-elements.f4a0c1a43cc1d8c287592710abe0889e.png?auto=format&fit=max&w=850&dpr=2 2x"
   alt="Hidden elements in the action list on a heatmap." /%}

### After attempting to create a heatmap, I see a "No Replay Data" state appear.{% #after-attempting-to-create-a-heatmap-i-see-a-no-replay-data-state-appear %}

The "No Replay Data" state means that Datadog could not find any Session Replays to use as a heatmap background that matches the current search filters. If you just started to record sessions with the [Browser SDK](https://github.com/DataDog/browser-sdk/blob/main/packages/rum/package.json), it may also take a few minutes for the Session Replay to be available for viewing.

### After attempting to create a heatmap, I see a "Not enough data to generate a heatmap" state appear.{% #after-attempting-to-create-a-heatmap-i-see-a-not-enough-data-to-generate-a-heatmap-state-appear %}

This means that Datadog was not able to match any user actions with the current selected replay. This happens for a variety of reasons, such as:

- Your application is not using the latest SDK version (>= 4.20.0).
- Your page has recently changed drastically.

### All of the user information on the page is empty.{% #all-of-the-user-information-on-the-page-is-empty %}

User information is not collected by default. Heatmaps use the user information available in your session data to display relevant insights on behavior.

## Further reading{% #further-reading %}

- [Session Replay for Browsers](https://docs.datadoghq.com/session_replay/browser.md)
- [Session Replay for Mobile](https://docs.datadoghq.com/session_replay/mobile.md)
- [Visualize user interactions with your pages by using Scrollmaps in Datadog Heatmaps](https://www.datadoghq.com/blog/visualize-behavior-datadog-scrollmaps/)