> 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/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, minimum page duration, and optionally a **funnel** (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.
#### Funnel conversion per element
When the heatmap is linked to a **funnel** (set in the heatmap's configuration — see section 8.6), the Top Elements report gains three additional columns for each element:
| Metric | Meaning |
| -------------------------- | ------------------------------------------------------------------- |
| **Funnel finished** | Sessions that interacted with this element and completed the funnel |
| **Funnel total** | Sessions that interacted with this element |
| **Funnel conversion rate** | The share of those sessions that went on to finish the funnel |
This answers *"which elements on this page are most — or least — associated with users completing the funnel?"* without any cross-referencing. Elements with fewer than twelve clicks are excluded from this view to avoid noisy percentages.
#### 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) |
| **Funnel** (optional) | Link to a funnel to show per-element conversion data in the Top Elements report (\[Chapter 12 — Funnels]) |
#### 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. Link a **funnel** to a heatmap to see per-element conversion rates alongside click metrics. 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.
