Understanding where your users actually interact with your product is different from what they say they do. PostHog heatmaps show you exactly where users click, scroll, and move their mouse—no guesswork. If you're relying on analytics alone to understand user behavior, heatmaps give you the missing visual layer.
Install PostHog and Enable Session Replay
Heatmaps depend on session replay data, so you need PostHog installed with replay enabled. If you already have PostHog running, check that session replay is active.
Install the PostHog SDK
Add PostHog to your project via npm. Import it in your main app file—it takes one line of initialization code.
npm install posthog-js
import posthog from 'posthog-js'
posthog.init('<your-project-api-key>', {
api_host: 'https://us.i.posthog.com',
})Verify Session Replay is Enabled
Session replay is enabled by default in PostHog. Go to Project Settings > Session Recording and confirm the toggle is on. If you need to customize recording—like excluding sensitive pages—do it here.
posthog.init('<your-project-api-key>', {
api_host: 'https://us.i.posthog.com',
session_recording: {
enabled: true,
capture_console: true,
},
})Deploy and Wait for Sessions
Push your changes and deploy. PostHog will start recording sessions automatically. You need at least a few sessions recorded before heatmaps will generate—usually ready within minutes.
Access and Configure Heatmaps
Once you have session replay data, heatmaps appear automatically. You can filter by page, user segment, or time range to focus on the behavior you care about.
Navigate to Session Replay
In PostHog, click Session Replay in the left sidebar. You'll see a list of recent sessions. Pick a session to open it, or use the filters at the top to find sessions matching specific criteria (e.g., users who hit an error, users from a specific location).
posthog.capture('page_view', {
page_title: document.title,
user_type: 'free_plan',
signup_source: 'google_ads',
})Open Heatmap View
Inside a session, click the Heatmap tab (next to the video player). This overlays click, scroll, and movement data on top of the webpage. Click zones show how many users clicked in that area; scroll depth shows how far down the page users went.
Filter Sessions for Heatmap Analysis
Use the Filters panel to narrow heatmaps to specific user segments or behaviors. For example, filter to users who dropped off at checkout, or users from mobile devices. Each filter updates the heatmap aggregation in real-time.
posthog.identify('user-123', {
email: '[email protected]',
plan_type: 'pro',
churn_risk: true,
})
posthog.capture('checkout_error', {
error_code: 'payment_declined',
step: 'billing_address',
})Interpret Heatmap Data and Fix Common Issues
Heatmaps can look noisy if you don't filter them right, or they might not show at all if replay data isn't flowing. Here's how to debug and use them effectively.
Understand Heatmap Color Intensity
Red/hot zones mean many users clicked or hovered there; blue/cool zones mean fewer interactions. A completely cold (blue) button might signal a UX problem—users aren't finding it or don't understand what it does.
posthog.capture('button_click', {
button_text: 'Subscribe Now',
button_location: 'pricing_page_hero',
section: 'above_fold',
})Check if Session Replay is Capturing
If you see no heatmaps, go to Project Settings > Session Recording and confirm Enabled is on. Also verify that the page isn't being excluded from recording—some companies block replay on sensitive pages like login or payment forms.
Aggregate Heatmaps Across Multiple Sessions
Instead of viewing one session at a time, you can generate a heatmap that combines clicks from many sessions. Use Recordings > Heatmap (at the top of the recordings list) to generate an aggregated view of all sessions matching your filters.
posthog.capture('page_view', {
pathname: window.location.pathname,
referrer: document.referrer,
})Common Pitfalls
- Heatmaps only show data for pages that were actually visited in recorded sessions. If you deploy a new landing page and no one has visited it yet, there's no heatmap to view—wait for traffic.
- If session replay is disabled (or consents aren't met), PostHog won't record sessions and you'll have no heatmap data. Always verify Project Settings > Session Recording is enabled and configured for your use case.
- Heatmaps for pages with dynamic content (SPAs, iframes, or heavily JavaScript-rendered pages) might miss some clicks if PostHog's DOM tracking doesn't catch the mutation. Test heatmaps on the specific pages you care about.
- Aggregating heatmaps across too many sessions or too long a time window can make the heatmap noisy and hard to interpret. Filter by specific user cohorts to get actionable insights.
Wrapping Up
Heatmaps turn fuzzy user behavior questions into visual facts. You can now see exactly where users click, what they ignore, and where friction lives. Pair heatmaps with session replay videos (watch one full session) and event analytics (how many users hit error state?) to get the full picture. If you want to track this automatically across tools, Product Analyst can help.