◈react-clickmap
Docs/API Reference

Components API

Wraps your app tree. Starts capture listeners, manages the event batcher, and provides context to child components.

`ClickmapProvider`

Wraps your app tree. Starts capture listeners, manages the event batcher, and provides context to child components.

TSX
import { ClickmapProvider, fetchAdapter } from "react-clickmap";

const adapter = fetchAdapter({ endpoint: "/api/clickmap" });

<ClickmapProvider
  adapter={adapter}
  projectId="my-app"
  capture={["click", "scroll", "rage-click", "dead-click"]}
  sampleRate={0.25}
  respectDoNotTrack
  respectGlobalPrivacyControl
>
  <App />
</ClickmapProvider>

Props

PropTypeDefaultDescription
adapterClickmapAdapterrequiredPersistence adapter
projectIdstring"default"Project scope for events
userIdstring—Optional user identifier
captureCaptureType[]["click"]Event types to capture
sampleRatenumber1Fraction of sessions to capture (0–1). Deterministic by session ID — the same session always gets the same decision.
flushIntervalMsnumber5000Batcher flush interval in milliseconds
maxBatchSizenumber100Flush when the queue reaches this size
respectDoNotTrackbooleanfalseHonor navigator.doNotTrack
respectGlobalPrivacyControlbooleanfalseHonor navigator.globalPrivacyControl
consentRequiredbooleanfalseRequire explicit consent before capturing
hasConsentboolean—Current consent state
maskSelectorsstring[][]CSS selectors for elements to mask
ignoreSelectorsstring[][]CSS selectors for elements to ignore

`Heatmap`

Renders a heatmap, clickmap, or scrollmap overlay on the page. Loads events from the adapter and draws them using WebGL (with Canvas fallback).

TSX
import { Heatmap } from "react-clickmap";

<Heatmap
  adapter={adapter}
  page="/pricing"
  type="heatmap"
  radius={25}
  opacity={0.6}
/>

Props

PropTypeDefaultDescription
adapterClickmapAdapterrequiredWhere to load events from
pagestring—Filter events by pathname
routeKeystring—Filter by SPA route key
type`"heatmap" \"clickmap" \"scrollmap"`"heatmap"Visualization mode
device`"all" \"desktop" \"tablet" \"mobile"`"all"Device filter
dateRange{ from: number; to: number }—Filter by timestamp range
radiusnumber20Heatmap point radius in pixels
opacitynumber0.65Overlay opacity (0–1)
gradientGradientMapdefault gradientCustom color gradient
showElementClicksbooleanfalseShow click-count badges on elements
elementClickMinClicksnumber1Minimum clicks to show a badge
elementClickMaxBadgesnumber20Maximum badges to render

Imperative handle

Use a ref to access export methods:

TSX
import { useRef } from "react";
import { Heatmap, type HeatmapHandle } from "react-clickmap";

const ref = useRef<HeatmapHandle>(null);

<Heatmap ref={ref} adapter={adapter} page="/pricing" />

// Export as PNG
await ref.current?.download("pricing-heatmap.png");

// Get data URL
const dataUrl = await ref.current?.toDataUrl();

// Get Blob
const blob = await ref.current?.toBlob();

`ScrollDepth`

Renders a vertical depth rail showing how far users scroll on a page.

TSX
import { ScrollDepth } from "react-clickmap";

<ScrollDepth
  adapter={adapter}
  page="/pricing"
  width={12}
/>

Props

PropTypeDefaultDescription
adapterClickmapAdapterrequiredWhere to load scroll events from
pagestring—Filter by pathname
widthnumber8Rail width in pixels

`AttentionHeatmap`

Combines click, pointer-move, and scroll data to render weighted attention zones. Areas with more interaction + deeper scroll depth get higher weights.

TSX
import { AttentionHeatmap } from "react-clickmap";

<AttentionHeatmap
  adapter={adapter}
  page="/pricing"
  radius={30}
  opacity={0.5}
/>

Props

PropTypeDefaultDescription
adapterClickmapAdapterrequiredWhere to load events from
pagestring—Filter by pathname
radiusnumber25Point radius
opacitynumber0.6Overlay opacity
device`"all" \DeviceType`"all"Device filter

`ComparisonHeatmap`

Renders two heatmaps side by side for before/after comparison. Useful for measuring the impact of design changes.

TSX
import { ComparisonHeatmap } from "react-clickmap";

<ComparisonHeatmap
  adapter={adapter}
  page="/pricing"
  beforeDateRange={{ from: lastWeekStart, to: lastWeekEnd }}
  afterDateRange={{ from: thisWeekStart, to: thisWeekEnd }}
/>

Props

PropTypeDefaultDescription
adapterClickmapAdapterrequiredWhere to load events from
pagestring—Shared page filter
routeKeystring—Shared route key filter
device`"all" \DeviceType`"all"Shared device filter
beforeDateRange{ from: number; to: number }requiredLeft panel time range
afterDateRange{ from: number; to: number }requiredRight panel time range

`HeatmapThumbnail`

Compact heatmap preview for dashboards, lists, and cards. Renders at a fixed size.

TSX
import { HeatmapThumbnail } from "react-clickmap";

<HeatmapThumbnail
  adapter={adapter}
  page="/pricing"
  width={300}
  height={200}
/>

Props

PropTypeDefaultDescription
adapterClickmapAdapterrequiredWhere to load events from
pagestring—Filter by pathname
widthnumber320Thumbnail width in pixels
heightnumber240Thumbnail height in pixels

`ElementClickOverlay`

Renders click-count badges anchored to visible DOM elements. Shows which buttons, links, and interactive elements get the most clicks.

TSX
import { ElementClickOverlay } from "react-clickmap";

<ElementClickOverlay
  adapter={adapter}
  page="/pricing"
  minClicks={3}
  maxBadges={12}
/>

Props

PropTypeDefaultDescription
adapterClickmapAdapterrequiredWhere to load click events from
pagestring—Filter by pathname
minClicksnumber1Minimum clicks to show a badge
maxBadgesnumber20Maximum badges to render

`useClickmap` hook

Access the capture engine context from any child component:

TSX
import { useClickmap } from "react-clickmap";

function StatusBar() {
  const { isCapturing, eventCount, queueSize } = useClickmap();

  return (
    <div>
      Capturing: {isCapturing ? "Yes" : "No"} |
      Events: {eventCount} |
      Queue: {queueSize}
    </div>
  );
}