Skip to main content

​
Overview

Heatmap tracking captures user interaction data including clicks, mouse movements, and scroll events. This data helps you visualize where users focus their attention and identify engagement patterns across your application.

​
How It Works

When enabled, the SDK automatically tracks:
  • Click events: Every click with coordinates and target element
  • Mouse movements: Sampled mouse position data (debounced to reduce volume)
  • Scroll events: Scroll position and depth tracking
All data includes viewport dimensions and element selectors for accurate replay and visualization.

​
Setup

1

Enable in Configuration

Set enableHeatmapTracking: true when initializing the SDK:
import { AnalyticsProvider } from "mentiq-sdk";

function App() {
  return (
    <AnalyticsProvider
      config={{
        apiKey: "your-api-key",
        projectId: "your-project-id",
        enableHeatmapTracking: true, // Enable heatmap tracking
      }}
    >
      <YourApp />
    </AnalyticsProvider>
  );
}
2

Automatic Data Collection

Once enabled, heatmap data is automatically collected in the background. The SDK:
  • Captures click coordinates and element information
  • Samples mouse movements every 500ms (debounced)
  • Tracks scroll position every 1000ms (debounced)
  • Includes viewport dimensions for responsive analysis
3

View in Dashboard

Access heatmap visualizations in your MentiQ dashboard to see:
  • Click density maps showing hotspots
  • Mouse movement trails
  • Scroll depth analytics
  • Element engagement rates

​
Data Structure

Each heatmap event includes: 
interface HeatmapData {
  x: number;              // X coordinate (pixels)
  y: number;              // Y coordinate (pixels)
  element?: string;       // HTML tag name (e.g., "button")
  selector?: string;      // CSS selector (e.g., "button#cta.primary")
  action: "click" | "move" | "scroll";
  viewport: {
    width: number;        // Viewport width
    height: number;       // Viewport height
  };
}

​
Manual Tracking with Components

For more control, use the HeatmapTracker component to track specific sections: 
import { HeatmapTracker } from "mentiq-sdk";

function ProductGrid() {
  return (
    <HeatmapTracker 
      trackClicks={true} 
      trackHovers={true} 
      element="product-grid"
    >
      <div className="grid">
        {/* Your products */}
      </div>
    </HeatmapTracker>
  );
}

​
Use Cases

​
Optimize CTAs

Identify which buttons and links get the most attention: 
<HeatmapTracker element="hero-section">
  <section className="hero">
    <button className="primary-cta">Get Started</button>
    <button className="secondary-cta">Learn More</button>
  </section>
</HeatmapTracker>

​
Analyze Content Engagement

See how far users scroll and where they stop reading: 
function BlogPost({ post }) {
  return (
    <HeatmapTracker element="blog-content" trackClicks={true}>
      <article>
        <h1>{post.title}</h1>
        <div>{post.content}</div>
      </article>
    </HeatmapTracker>
  );
}

​
E-commerce Product Pages

Track which product images and details users interact with: 
<HeatmapTracker element="product-page" trackClicks={true} trackHovers={true}>
  <div>
    <ProductGallery images={product.images} />
    <ProductDetails details={product.details} />
    <AddToCartButton />
  </div>
</HeatmapTracker>

​
Performance Considerations

The SDK uses debouncing to minimize performance impact:
  • Mouse movements are sampled every 500ms
  • Scroll events are throttled to 1000ms
  • Events are batched before sending to reduce network requests

​
Implementation Details

From src/analytics.ts:250-319: 
private setupHeatmapTracking(): void {
  const trackClick = (event: MouseEvent) => {
    const heatmapData: HeatmapData = {
      x: event.clientX,
      y: event.clientY,
      element: (event.target as HTMLElement)?.tagName?.toLowerCase(),
      selector: this.getElementSelector(event.target as HTMLElement),
      action: "click",
      viewport: {
        width: window.innerWidth,
        height: window.innerHeight,
      },
    };

    this.enqueueEvent(createEvent("heatmap", "click", { heatmap: heatmapData }));
  };

  // Debounced mouse movement tracking (500ms)
  const trackMouseMove = debounce((event: MouseEvent) => {
    // ... similar structure for mouse movements
  }, 500);

  // Debounced scroll tracking (1000ms)
  const trackScroll = debounce(() => {
    // ... scroll position tracking
  }, 1000);

  window.addEventListener("click", trackClick);
  window.addEventListener("mousemove", trackMouseMove, { passive: true });
  window.addEventListener("scroll", trackScroll, { passive: true });
}

​
Privacy Considerations

Heatmap tracking captures user interaction patterns. Ensure compliance with privacy regulations:
  • Inform users about heatmap tracking in your privacy policy
  • Consider disabling on pages with sensitive information
  • Respect user opt-out preferences

​
Disabling for Specific Pages

You can conditionally enable heatmap tracking: 
function App() {
  const isPublicPage = useIsPublicPage();

  return (
    <AnalyticsProvider
      config={{
        apiKey: "your-api-key",
        projectId: "your-project-id",
        enableHeatmapTracking: isPublicPage, // Only track on public pages
      }}
    >
      <YourApp />
    </AnalyticsProvider>
  );
}

​
Troubleshooting

​
Events Not Appearing in Dashboard

  1. Verify enableHeatmapTracking: true in config
  2. Check browser console for errors (enable debug: true)
  3. Ensure events are being flushed (check queue size)

​
Too Much Data

Increase debounce intervals or reduce tracking scope: 
// Only track clicks, not movements
<HeatmapTracker trackClicks={true} trackHovers={false}>
  {/* content */}
</HeatmapTracker>

Build docs developers (and LLMs) love

Get started for freeTalk to us