clickmap
v1.0.1
Published
Lightweight click tracking script for ClickMap analytics
Maintainers
valoup917Readme
ClickMap
Lightweight click tracking script for ClickMap analytics. Captures user clicks with rage click detection and sends them to the ClickMap API.
Installation
npm install clickmapUsage with Next.js / React
1. Create the tracker component
Create a file components/ClickMapTracker.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;
}2. Add to your layout
In your app/layout.tsx:
import ClickMapTracker from '@/components/ClickMapTracker';
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
<html lang="en">
<body>
<ClickMapTracker />
{children}
</body>
</html>
);
}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
sendBeaconAPI for reliable, non-blocking transmission - Auto-flush: Remaining clicks are sent when user leaves the page
API
ClickMap.init(config)
Initialize click tracking with the provided configuration.
ClickMap.stop()
Stop tracking and flush any remaining queued clicks.
Data Collected
Each click event includes:
x_percent/y_percent: Click position as percentage of document dimensionsscroll_y: Vertical scroll position in pixelsscreen_width: Viewport width (for desktop/mobile segmentation)element_selector: CSS selector of the clicked elementurl: Current page pathis_rage_click: Whether the click is part of a rage click sequencetimestamp: ISO timestamp of the click
License
MIT