ClickMap

Lightweight click tracking script for ClickMap analytics. Captures user clicks with rage click detection and sends them to the ClickMap API.

Installation

``bash
npm install clickmap
`

Usage with Next.js / React

$3

Create a file components/ClickMapTracker.tsx:

`tsx
'use client';

import { useEffect } from 'react';
import ClickMap from 'clickmap';

export default function ClickMapTracker() {
useEffect(() => {
ClickMap.init({
apiKey: 'your-api-key-here',
debug: false,
gdprMode: false,
batchSize: 10,
});

return () => {
ClickMap.stop();
};
}, []);

return null;
}
`

$3

In your app/layout.tsx:

`tsx
import ClickMapTracker from '@/components/ClickMapTracker';

export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (



{children}


);
}
`

Configuration Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| apiKey | string | required | Your ClickMap project API key (UUID format) |
| debug | boolean | false | Enable console logging for debugging |
| gdprMode | boolean | false | When enabled, clicks on form inputs (input, textarea, select) are not tracked |
| batchSize | number | 10 | Number of clicks to collect before sending to the API |

Features

- Lightweight: Minimal bundle size, no dependencies
- Batched requests: Clicks are batched to reduce network requests
- Rage click detection: Automatically detects frustrated rapid clicking
- GDPR mode: Option to exclude form inputs for privacy compliance
- Non-blocking: Uses sendBeacon API for reliable, non-blocking transmission
- Auto-flush: Remaining clicks are sent when user leaves the page

API

$3

Initialize click tracking with the provided configuration.

$3

Stop tracking and flush any remaining queued clicks.

Data Collected

Each click event includes:

- x_percent / y_percent: Click position as percentage of document dimensions
- scroll_y: Vertical scroll position in pixels
- screen_width: Viewport width (for desktop/mobile segmentation)
- element_selector: CSS selector of the clicked element
- url: Current page path
- is_rage_click: Whether the click is part of a rage click sequence
- timestamp`: ISO timestamp of the click

License

MIT