> For the complete documentation index, see [llms.txt](https://docs.humblytics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humblytics.com/understanding-your-data/understanding-heatmap.md).

# Understanding Heatmap

See where visitors click and how far they scroll, drawn on top of a screenshot of your real page.

A heatmap colors your page by activity: warm colors (red, orange) show where people click the most, and cool colors (blue) show where they click least. A scroll map shows how many visitors reach each part of the page.

Go to **Observe → Heatmaps**.

## Add a page

1. Click **Add page**.
2. Pick a page from the suggestions, which are your most-visited pages that aren't tracked yet. You can also search your pages, or type any URL.
3. Humblytics captures a screenshot and starts drawing the heatmap from your existing click and scroll data.

Heatmap pages are counted per site: 1 on Business, 5 on Scale, and unlimited on Agents plans. At your limit, **Add page** changes to **Upgrade**. See [Plan limits & upgrades](https://docs.humblytics.com/understanding-your-data/plan-limits-and-upgrades.md).

## Controls

| Control              | What it does                                                                                                                                                |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Page picker**      | Shows the current page and its visitors. Use it to switch between tracked pages or to add another page.                                                     |
| **Clicks / Scroll**  | Switch between the click heatmap and the scroll map.                                                                                                        |
| **Mobile / Desktop** | Show the page as visitors see it on a phone (390px wide) or on a desktop (up to 800px wide in the viewer). People behave differently on each.               |
| **Heat intensity**   | Make hotspots stronger or softer.                                                                                                                           |
| **Capture strip**    | Shows when the screenshot was taken, for example *Captured Sep 15 · desktop*. If a page has earlier captures, open it to choose which one the heat sits on. |
| **Recapture**        | Take a fresh screenshot after a redesign. See [Versions](#versions) below.                                                                                  |
| **⋯ (page actions)** | Download the heatmap image, download scroll details, or **Remove page**.                                                                                    |

Beside the screenshot:

* **Summary stats:** clicks (or taps) for the selected device, the share of clicks on the top element, the share of visitors who scroll past the first screen, and the share who reach the end of the page. A stat with no data is left out instead of showing 0.
* **Top clicked elements:** every clicked element, ranked, with its click count and share of clicks. The top elements are labeled on the screenshot with their rank; hover a row to spotlight that element.
* **Scroll details:** average depth and how many visitors reached each 10% slice of the page. The top slice is always 100%, because everyone sees the top of the page.

### Test this element

Each row in the element list has a **Test this element** action. It starts a new A/B test in the visual editor with that element already selected, so you can go from "people keep clicking this" to a test in one step. See [Understanding Experiments](https://docs.humblytics.com/understanding-your-data/understanding-experiments.md).

## The screenshot

* **Clicks:** color-coded hotspots on the page, with the page dimmed so the hotspots stand out.
* **Scroll:** depth markers down the side of the page (100%, 80%, 60%, 40%, 20%). A **fold line** marks where the first screen ends on the selected device and shows the share of visitors who scroll past it. The line is hidden when the whole page fits on one screen. Scroll data covers all devices together.

## Versions

Each time you recapture, Humblytics starts a new heatmap version and keeps the old ones. Open the capture strip to switch between versions. This lets you compare behavior before and after a redesign.

{% hint style="info" %}
**Seeing a date range mismatch?** The heatmap version you're viewing falls outside the dates picked at the top of the page. Pick a wider date range, or switch to a different version.
{% endhint %}

## What to look for

* **Hotspots on things that aren't links:** people expect them to be clickable.
* **A cold main CTA:** it isn't standing out, or it sits below where most people stop scrolling.
* **The fold line above your key content:** most visitors never see it. Move it up or shorten what comes before it.
* **Mobile vs. desktop differences:** a layout that works on desktop can bury content on mobile.

## Troubleshooting

**Screenshot capture timed out.** Humblytics captures a live screenshot of your page in a headless browser. Heavy pages, slow third-party scripts, or login walls can push capture past the timeout.

1. **Retry.** Temporary slowdowns often clear on a second attempt.
2. **Simplify the page.** Temporarily disable heavy widgets, chat widgets, or autoplay video on the URL you are capturing.
3. **Use a public URL.** Pages behind a login or geo-block may never finish loading for the capture service.
4. **Check the URL.** Confirm the page URL in Heatmaps matches the live page, including `www` vs. non-`www`.

Capture timeouts don't affect click or scroll data already collected for the page, only the screenshot.

**Couldn't export the heatmap image.** The download action saves the on-screen heatmap as a PNG from the screenshot already loaded in the viewer. If it fails, wait a few seconds and retry. If it keeps failing, click **Recapture** so Humblytics stores a fresh screenshot, then download again. Export failures don't use up a heatmap page slot and don't trigger a new capture on their own.
