> For the complete documentation index, see [llms.txt](https://docs.fullsession.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fullsession.io/8.-heatmaps.md).
# 8. Heatmaps
A single session shows you what *one* person did. A **heatmap** aggregates many sessions into one color-coded picture of behavior on a page — where people click, how their cursor moves, and how far they scroll. In FullSession, a heatmap is a **saved configuration** you build for a specific page, audience, and device, and it's rendered as an overlay on a real snapshot of your page.
***
### 8.1 How Heatmaps Work
#### The three map types
FullSession offers three heatmap types, switched with a toggle at the top of the heatmap view:
| Type | Button | Shows |
| ------------ | ---------------- | --------------------------------------- |
| **Click** | **Clicks Map** | Where visitors clicked or tapped |
| **Movement** | **Movement Map** | Where the mouse/cursor moved |
| **Scroll** | **Scroll Map** | How far down the page visitors scrolled |
#### Rendered on a real snapshot
A FullSession heatmap isn't drawn on a generic screenshot. When you build one, FullSession:
1. Finds **sessions that match your filters** (page, segment, device, date, minimum page duration).
2. Picks a **representative session** — typically the one with the most scroll depth (or the longest visit) on that page.
3. Captures that session's **full DOM snapshot** (the actual page, with its real styles and structure).
4. **Overlays** the aggregated heatmap data on top of that snapshot inside a scaled iframe.
Because the overlay sits on a genuine snapshot of your page, the hotspots line up with the real layout your visitors saw. You can swap to a different representative snapshot at any time with **Update Snapshot** (section 8.7).
#### Creating a heatmap
1. Go to **Heatmaps** and create a new heatmap.
2. Choose the **page**:
* **Page** — pick from your site's known pages, or
* **URL** — enter a URL pattern (supports a `*` wildcard for matching variations).
3. Set the **filters** — segment, device, date range, and minimum page duration (section 8.6).
4. FullSession renders the map. Switch between **Clicks**, **Movement**, and **Scroll** as needed.
5. **Save** it so you (and your team) can return to it later (section 8.7).
> **Tip** — heatmaps draw from your **recorded sessions**. A brand-new page with little traffic will produce a sparse map; give it time to collect visits, or widen the date range.
***
### 8.2 Click Map
The **Clicks Map** overlays your page with a heat visualization of where visitors clicked or tapped — the warmer the area, the more interaction it received.
Switching to **Rage Clicks**, **Error Clicks**, or **Dead Clicks** turns the click map into a **frustration map** — instantly showing *which parts of the page* are causing problems, not just where people click.
#### Page statistics
Alongside the map, a statistics panel summarizes the page's health and traffic for your filters, including:
* **Total views** and **unique users**
* **Average time on page** and **average load time**
* Totals for **Rage**, **Error**, and **Dead** clicks
This gives you the headline numbers behind the visualization at a glance.
> **Finding frustration by element** — to see *which specific elements* receive the most rage/dead/error clicks (ranked, with counts), use the **Top Elements report** in section 8.5. FullSession does not have a separate "raging elements" page; that data lives in the click-map element report.
***
### 8.3 Movement Map
The **Movement Map** visualizes where visitors moved their **mouse/cursor** across the page. Because cursor movement often tracks where people are looking and reading, it's a useful proxy for attention on desktop.
#### What it reveals
* **Areas of attention** — sustained cursor presence often indicates where visitors focused.
* **Reading patterns** — movement can hint at how people scan a layout.
* **Ignored regions** — cold areas suggest content visitors never engaged with.
> **Movement is cursor movement, not hover-only.** The Movement Map shows where the pointer traveled across the page; it's most meaningful for desktop sessions, where a mouse is in play. On touch devices, interaction is better understood through the Clicks Map (taps are captured as clicks).
***
### 8.4 Scroll Map
The **Scroll Map** shows how far down the page visitors actually scrolled — answering the single most important question about any long page: *how much of it does anyone see?*
#### What it shows
The scroll map colors the page from top to bottom by what share of visitors reached each depth, and it marks several reference lines:
| Marker | Meaning |
| ------------------ | ----------------------------------------------------------------------- |
| **Average Fold** | The average scroll depth visitors reached (e.g. *"Average Fold 450px"*) |
| **25% percentile** | 25% of visitors scrolled at least this far |
| **50% percentile** | The median scroll depth — half of visitors reached this point |
| **75% percentile** | 75% of visitors scrolled at least this far |
#### Reading the scroll map
* If your key message or CTA sits **below the average fold**, most visitors never see it without scrolling.
* The gap between the **25%** and **75%** lines shows how *consistent* scrolling is — a tight band means most visitors behave similarly; a wide band means behavior varies.
* A steep fall-off near a percentile line tells you where visitors tend to stop.
> **Tip** — pair the Scroll Map with the Clicks Map. If an important button is below the average fold *and* getting few clicks, the fix is usually placement: move it up.
***
### 8.5 Top Elements & the Element Report
Beyond the visual overlay, the Clicks Map includes a **Top Elements report** — a ranked list of the page's most-interacted elements, with detailed metrics. This is where heatmaps connect to the **Named Elements** and **Watch Rules** from \[Chapter 7 — Recording Rules & Element Tracking].
#### What each element shows
For every ranked element, the report displays its **CSS selector** (copyable) and metrics including:
* **Total clicks**, with the **percentage of sessions** that clicked it
* **Users who clicked**, with the **percentage of unique users**
* Per-element frustration counts — **rage**, **error**, and **dead** clicks
* Interaction detail such as **hover-to-click** counts and **average hover time**
The ranking follows whichever aggregation is selected — choose **Rage Clicks**, for example, and the list re-ranks to show the elements causing the most frustration first.
#### Actions on each element
| Action | What it does |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Label** | Give the element a human-readable name (creates a **Named Element**) so it appears clearly in reports and funnels |
| **View Sessions** | Jump to the sessions where visitors interacted with this element |
#### Picking elements directly on the heatmap
The element report includes an **Element Selector** mode that lets you pick elements **directly on the heatmap** to track — creating or updating a **Watch Rule** (\[Chapter 7, section 7.4]) without hand-writing a selector. This is the most convenient way to start tracking a specific element.
There's also a **Hidden Elements** toggle to show or hide elements that are no longer present or visible in the captured snapshot — useful when reconciling a heatmap against a page that has since changed.
#### Per-element details
Clicking an element on the map opens a detail popup with its full stats — number of clicks and hovers, unique-session clicks, visitor click rate, hover-to-click rate, average hover time, and timing metrics — so you can analyze one element in depth.
> **Tip** — use **View Sessions** on a high-frustration element to watch real recordings of people struggling with it, then confirm the cause before filing a fix.
***
### 8.6 Filtering, Segments & Device Views
A heatmap of *all* visitors is useful, but the real insight comes from scoping it. FullSession heatmaps support a specific set of filters, applied when you configure the heatmap.
#### Direct heatmap filters
| Filter | Use it for |
| ------------------------- | ----------------------------------------------------------------------- |
| **Page / URL** | The page to analyze — a known page or a URL pattern (with `*` wildcard) |
| **Segment** | The audience to focus on (\[Chapter 11 — Segments]) |
| **Device** | Desktop, Tablet, or Mobile (see below) |
| **Date range** | A relative preset or a custom start/end window |
| **Minimum page duration** | Excludes very short, bounce-like visits (helps filter out noise) |
#### Filtering by audience uses Segments
> Heatmaps don't have direct filters for **country**, **traffic source**, **new vs. returning**, **browser**, or **OS**. To narrow a heatmap by any of those, build a **Segment** with those conditions and select it as the heatmap's segment. Segments are FullSession's reusable audience definitions — see \[Chapter 11 — Segments].
#### Device views
Switch the heatmap between three device renderings, each with its own viewport size:
| Device | Viewport |
| ----------- | ----------- |
| **Desktop** | 1920 × 1080 |
| **Tablet** | 768 × 1024 |
| **Mobile** | 412 × 915 |
The snapshot and overlay are scaled to fit your screen while preserving the page's responsive layout. Always review **desktop and mobile separately** — the same page often behaves very differently across viewports, and a CTA that's a hotspot on desktop can be missed entirely on mobile.
#### Comparing segments
> There's **no built-in side-by-side segment comparison** in a single heatmap. To compare two audiences, create **two saved heatmaps** for the same page — one per segment — and view them side by side. (See section 8.7 for saving and duplicating.)
***
### 8.7 Saving, Managing & Updating Heatmaps
Because heatmaps are configured artifacts, FullSession keeps a managed library of them per site.
#### The heatmap library
Your saved heatmaps appear in a list showing each one's **name, URL, creator, and date**. From here you can **edit**, **duplicate**, or **delete** a heatmap, and search by title, URL, or creator. This makes it easy to maintain a standing set of heatmaps for the pages you watch most.
#### Saving and duplicating
* **Save** — update the current heatmap's configuration.
* **Save As** — create a copy under a new title (handy for spinning up a segment- or device-specific variant).
* **Duplicate** — one-click copy from the list.
Duplicating is the practical way to build the **two-heatmap comparison** described in section 8.6 — duplicate a heatmap, change the segment or device, and view both.
#### Update Snapshot
The map is drawn on one representative session's snapshot. If that snapshot doesn't represent the page well (or the page has changed), click **Update Snapshot** to re-pick a different representative session and re-render the overlay.
#### Heatmaps in the session player
Heatmaps are also reachable from the **session player**: the player offers a **Session Replay / HeatMaps** tab pair (\[Chapter 6, section 6.1]), so you can flip from watching one visitor to seeing the aggregate heat for that page.
#### Exporting
> **Heatmap export is not yet available.** A download option is marked **coming soon**. For now, share findings by saving the heatmap (so teammates can open it directly) or by capturing your own screenshot.
> **The big picture** — FullSession heatmaps are saved configurations rendered over a real page snapshot, in three flavors (**Clicks**, **Movement**, **Scroll**). The Click Map doubles as a frustration map via its **Rage / Error / Dead** aggregations, and the **Top Elements report** ranks the exact elements driving interaction and frustration — with one click to label them or watch the sessions behind them. Scope by device, date, page-duration, and **Segment** (for geo/source/returning audiences), and manage everything from the heatmap library. There's no separate raging-elements page, no segment-comparison view, and export is still coming.
***
> **Next up:** \[Chapter 9 — Dashboards] zooms out from individual pages to your whole product, assembling session metrics, heatmap insights, and custom events into shareable dashboards.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.fullsession.io/8.-heatmaps.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.