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

> For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt).

# Heatmaps

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com, us2.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site.md). ({% placeholder "user-datadog-site-name" /%}).
{% /alert %}

{% /callout %}

{% 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/privacy_options.md?platform=browser#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." /%}

### Analyzing heatmaps beyond replay retention{% #analyzing-heatmaps-beyond-replay-retention %}

In Product Analytics, click data outlives the Session Replay used as a background. See Data retention. To view a heatmap for a period older than your replay retention:

1. Set the date range to a period within the last 30 days, so a heatmap renders with a background from a recent replay.
1. Click Save on the current screenshot to pin it.
1. Set the date range back to the period you want to analyze.

Your older click data appears on the pinned screenshot. You can also use Take new screenshot to capture a specific state from your live application.

**Note**: The background reflects your application as it looked recently, not as it looked during the period you are analyzing. If your page layout changed in between, clicks can appear over the wrong elements.

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

A heatmap combines two pieces of data (the **overlay** - clicks and scrolls, and the **background screenshot**), and Datadog retains each for a different period:

| Data                                                  | Source                       | Retention          |
| ----------------------------------------------------- | ---------------------------- | ------------------ |
| **Overlay** (clicks and scrolls) in RUM               | RUM action events            | 30 days            |
| **Overlay** (clicks and scrolls) in Product Analytics | Product Analytics click data | 15 months          |
| **Background screenshot** in both                     | Session Replay               | 30 days by default |

A heatmap needs both to render. If you select a time frame where click data still exists but no replay remains to use as a background, the heatmap shows "No Replay Data" even though you can still query those actions in the Analytics Explorer.

In Product Analytics, if you expect to analyze a view over a period longer than 30 days, save a screenshot for it while replays are still available. Saving a screenshot extends the retention of the replay behind it to 15 months, so the heatmap keeps rendering for as long as Datadog retains your Product Analytics click data. See Analyzing heatmaps beyond replay retention.

In RUM, action events expire after 30 days, so heatmaps are not available beyond that window.

For the retention periods that apply to other data types, see [Data retention periods](https://docs.datadoghq.com/data_security/data_retention_periods.md). To extend retention on individual replays, see [Extend data retention](https://docs.datadoghq.com/session_replay.md#extend-data-retention).

## 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 Replay to use as a heatmap background. Common causes:

- Your selected time frame is older than your Session Replay retention, which is 30 days by default. Click data can still exist, but no replay remains to use as a background. See Analyzing heatmaps beyond replay retention.
- No replay matches your current search filters.
- You recently started recording with the [Browser SDK](https://github.com/DataDog/browser-sdk/blob/main/packages/rum/package.json), and the replay is not yet available. This can take a few minutes.

### 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 %}

Additional helpful documentation, links, and articles:

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