You ship a new landing page and traffic comes in, but you have no idea what's actually getting clicked or where users scroll to—you're flying blind. Heatmaps solve this by showing you exactly where users interact with your pages in a visual overlay. PostHog's heatmaps build on top of session recording to automatically aggregate interaction patterns without any extra setup.
How PostHog Heatmaps Work
Heatmaps in PostHog are automatically generated from session recording data. Instead of hunting through individual recordings, you get an aggregated visual summary of where users click, move, and scroll across a URL.
Understanding Heatmap Types and What They Show
PostHog generates two types of heatmaps from recording data. Click Heatmaps show the frequency and location of clicks across page elements—red zones indicate the highest-clicked areas, cooling through orange and yellow to blue for less-clicked regions. Scroll Depth visualizes how far down the page users typically scroll before leaving, using a gradient to show where the majority of users stop scrolling. Both types are generated automatically without any configuration beyond enabling session recording.
// Enable session recording—heatmaps are generated automatically
posthog.init('your-api-key', {
api_host: 'https://app.posthog.com',
enable_recording: true, // Heatmap data comes from recordings
session_recording: {
sample_rate: 1.0 // Record 100% of sessions to get heatmaps faster
}
});How PostHog Collects and Processes Interaction Data
When session recording is enabled, PostHog captures every click, mouse movement, and scroll event in real-time. The heatmap engine then processes this data and aggregates it across all recorded sessions for each unique URL. PostHog respects your privacy settings—if you enable text masking or input masking during recording, that data is excluded from heatmaps. This keeps heatmap generation both privacy-safe and automatic. The result is a single visual overlay that summarizes interaction patterns across potentially thousands of sessions.
// Configure privacy settings that affect what interaction data heatmaps collect
posthog.init('your-api-key', {
api_host: 'https://app.posthog.com',
enable_recording: true,
mask_all_text: false, // Set to true to mask all text in recordings
mask_all_inputs: true, // Masks form inputs by default for security
recording_console_log_enabled: true // Capture console logs in sessions
});Enabling and Viewing Heatmaps in PostHog
Once your sessions are recorded, accessing and interpreting heatmaps is straightforward. The PostHog UI handles visualization and filtering automatically, and you can dive deeper with segmentation.
Access and View Heatmaps in the PostHog Dashboard
Navigate to Session Recordings > Heatmaps in the PostHog app. You'll see a list of URLs on your site that have sufficient session data. Select any URL, and PostHog overlays the heatmap directly on a page screenshot. The overlay shows color-coded regions representing interaction density. You can toggle between Click Heatmaps and Scroll Depth views using the buttons at the top of the viewer. The page preview updates immediately to show the selected heatmap type.
// Retrieve heatmap data programmatically via the PostHog API
fetch('https://app.posthog.com/api/projects/PROJECT_ID/heatmaps', {
method: 'GET',
headers: {
'Authorization': 'Bearer YOUR_PERSONAL_API_KEY',
'Content-Type': 'application/json'
}
})
.then(res => res.json())
.then(data => {
console.log('Available heatmaps:', data);
// Returns list of URLs with heatmap data and interaction metrics
});Filter Heatmaps by User Segment
Use the Filters panel in the heatmap viewer to narrow down which sessions are included in the aggregation. You can filter by user properties (e.g., plan tier, signup date, country), cohorts, or custom events. This is powerful for comparing heatmaps across different user segments. Filter to show heatmaps only for users who converted vs. users who churned—you'll often see significant behavioral differences that reveal optimization opportunities specific to each segment.
// Set user properties to enable filtering and segmentation in heatmaps
posthog.identify('user-456', {
email: '[email protected]',
plan: 'enterprise',
signup_date: '2025-01-01',
monthly_spend: 2500,
churned: false,
industry: 'SaaS'
});
// These properties become available as filters in the heatmap viewer
// Segment heatmaps by plan, spending, churn status, etc.Compare Heatmaps Over Time and After Changes
Click the Date Range selector to view heatmaps from different time periods. This helps you detect behavior shifts after a design update, A/B test, or feature launch. After redesigning your checkout button, compare the heatmap from before the change to after. If the new button has a higher click rate, the redesign likely improved visibility. Comparing before-and-after heatmaps is a quick, visual way to validate whether a UI change achieved your goal without digging through logs.
// Track UI changes and feature deployments as events for correlation
posthog.capture('feature_deployed', {
feature: 'checkout_redesign',
component: 'payment_button',
change_type: 'styling_and_copy',
new_copy: 'Complete Purchase',
version: 'v2.5.0',
deployed_at: new Date().toISOString()
});
// This event timestamp helps correlate UI changes with heatmap behavior shiftsCommon Pitfalls
- Heatmaps require sufficient data volume. Unless a URL has roughly 100+ recorded sessions, PostHog won't generate a heatmap. Low-traffic pages need days or weeks to accumulate data.
- Sample rate affects heatmap speed. Recording 100% of sessions gets you heatmaps faster but uses more bandwidth. On high-traffic apps, sample down to 0.1 (10%) to control costs, but expect slower heatmap generation.
- Context is everything. A click hotspot might indicate user confusion, accidental clicks, or genuine interest. Always pair heatmaps with session replay to understand the why behind the clicks.
- Dynamic layouts cause misalignment. If a URL serves different layouts across sessions via A/B tests, personalization, or feature flags, the heatmap overlay will misalign because PostHog segments by URL, not by page structure. High-variance pages produce noisy heatmaps.
Wrapping Up
Heatmaps cut through guesswork by showing exactly where users interact with your pages. Enable session recording in PostHog, let data accumulate to 100+ sessions, then dive into the Heatmaps viewer to spot friction and high-engagement zones. Pair them with session replays and segmentation for deeper insights. If you want to track this automatically across tools, Product Analyst can help.