Learn react-clickmap
Guides, API references, and practical examples for building privacy-first heatmap analytics.
Overview
Start here — installation, architecture, and core concepts.
Architecture Overview
react-clickmap has two pipelines: **capture** (browser → database) and **render** (database → heatmap overlay). They're connected by the adapter interface, which you control.
→Getting Started
Wrap your app with `ClickmapProvider` and drop a `Heatmap` overlay wherever you want to visualize behavior:
→Guides
Step-by-step walkthroughs for common integration patterns.
Add-on Packages
react-clickmap ships first-party add-on packages for common integrations. The core library stays lightweight — install only what you need.
→Next.js App Router Integration
This guide shows how to set up react-clickmap in a Next.js App Router project, from installation to a working heatmap overlay with database persistence.
→Persistence Guide
react-clickmap doesn't care where you store events. The adapter interface has two required methods — `save()` and `load()` — and two optional ones. This guide walks through every built-in adapter and shows you how to set up database persistence from scratch.
→Privacy and Consent Guide
react-clickmap is designed for privacy-first analytics. It collects no PII by default, uses no cookies, does no fingerprinting, and respects browser privacy signals out of the box.
→Rendering and Performance Guide
This guide covers how react-clickmap renders heatmap overlays, the rendering engine tiers, and how to optimize performance for large datasets.
→API Reference
Detailed reference for every component, hook, and type.
Adapters API
Every adapter implements this interface. `save` and `load` are required; `deleteEvents` and `loadAggregated` are optional.
→Components API
Wraps your app tree. Starts capture listeners, manages the event batcher, and provides context to child components.
→Event Model API
Every interaction captured by react-clickmap produces a `CaptureEvent`. This page documents the event structure, types, and fields.
→Examples
Copy-paste recipes for specific use cases.
Example: Element Click Overlay
The `ElementClickOverlay` renders floating badges on top of your page's elements showing how many times each one was clicked. It's useful for quickly spotting which buttons, links, and interactive elements get the most attention — and which ones trigger rage or dead clicks.
→Example: Export Heatmap Image
The `<Heatmap>` component exposes an imperative handle via React ref that lets you export the rendered canvas as an image. Use this to build "Download as PNG" buttons, generate thumbnails, or pipe heatmap images into reports.
→