Heatmaps show exactly where users click, scroll, and move their mouse. PostHog generates heatmaps from session recordings—enable them once, then analyze them in the UI.
Enable Session Recording for Heatmaps
Heatmaps need session recording enabled. This tells PostHog to capture DOM changes, clicks, scrolls, and mouse movement.
Initialize PostHog with session recording
Add the PostHog SDK and set session_recording.enabled: true in your init config. This activates automatic capture of all interaction data.
import posthog from 'posthog-js'
posthog.init('YOUR_POSTHOG_API_KEY', {
api_host: 'https://app.posthog.com',
session_recording: {
enabled: true,
sampleRate: 1.0
}
})Mask sensitive form fields
Protect PII by masking form inputs. Set maskAllInputs: true to hide passwords, credit cards, and email inputs from session playback. Use blockSelectors to hide specific elements entirely.
Deploy and verify
Push your changes live. Open Session Replay in PostHog—you should see new sessions within a few minutes. Click any session and toggle Heatmap to see the overlay.
// After deploying, verify session recording is working
// In PostHog UI: Session Replay → (sessions appear here)
// Each session has a Heatmap button to view the overlay
// The heatmap shows clicks (red dots), scrolls, and mouse movementsession_recording.enabled is missing or false, PostHog won't capture interaction data and heatmaps won't be available.View and Filter Heatmaps
Once sessions are recording, you can view heatmaps in PostHog and filter them by page, user segment, or custom event.
Open a session and view the heatmap
Go to Session Replay in the left sidebar. Click any session to open the replay player. Look for the Heatmap toggle or button to enable the heatmap overlay on top of the page.
Filter sessions by URL and properties
Use the Filter panel to narrow sessions by URL (to see heatmaps for a specific page), Device (mobile vs. desktop), or custom properties like user tier. This shows you heatmaps only for the cohort you care about.
// In PostHog, filter sessions programmatically (if using the API)
// Example: Get sessions for a specific page
fetch('https://app.posthog.com/api/projects/PROJECT_ID/events/', {
method: 'POST',
headers: { 'Authorization': 'Bearer TOKEN' },
body: JSON.stringify({
where: [
'event = "$pageview"',
'properties.$current_url = "/pricing"'
],
select: ['$session_id']
})
})
.then(r => r.json())
.then(data => console.log(`${data.results.length} sessions on /pricing`))Correlate Heatmaps with Custom Events
Heatmaps show *how* users interact. Pair them with custom events to understand *why*.
Log events for user interactions
Use posthog.capture() to log events when users click buttons, submit forms, or interact with features. PostHog ties these events to the session, so you can later filter heatmaps for users who triggered specific events.
// Log button clicks
document.getElementById('signup-btn').addEventListener('click', () => {
posthog.capture('signup_button_clicked', {
button_location: 'hero',
variant: 'primary'
})
})
// Log form submission
const form = document.getElementById('contact-form')
form.addEventListener('submit', (e) => {
e.preventDefault()
posthog.capture('contact_form_submitted', {
fields: form.elements.length,
time_spent_seconds: 45
})
})Filter heatmaps by event and cohort
In Session Replay, filter for sessions where contact_form_submitted was triggered. Then view the heatmap for only those sessions to see how users who converted interacted with the page. Repeat for different cohorts (new vs. returning, paid vs. free).
Common Pitfalls
- Forgetting to enable
session_recording.enabled: true—without this, PostHog captures events but not the DOM interactions needed for heatmaps. - Setting
sampleRatetoo low (less than 0.5) creates gaps in heatmap data. Start with 1.0 and only reduce if storage costs spike. - Not masking sensitive fields—passwords, credit cards, and PII will be visible in playback. Always use
maskAllInputs: trueorblockSelectorsfor sensitive elements. - Assuming heatmaps are real-time—session processing has a 5-10 minute lag, so new sessions won't appear in heatmaps immediately.
Wrapping Up
You've now enabled heatmap tracking and can view interaction overlays on your pages. Pair heatmaps with custom events to understand where users click, drop off, and convert. If you want to track this automatically across tools, Product Analyst can help.