Microsoft Clarity in React & Next.js

Updated on Leave a Comment on Microsoft Clarity in React & Next.js

1. Introduction

Microsoft Clarity is a free user behavior analytics tool that provides session recordings, heatmaps, and interaction insights. Unlike traditional analytics platforms, Clarity focuses on how users actually interact with your application, making it extremely useful for debugging UX issues, identifying friction points, and improving conversion rates.

In React and Next.js applications, Clarity helps us:

  • Record real user sessions

  • Analyze click, scroll, and navigation behavior

  • Detect rage clicks, dead clicks, and excessive scrolling

  • Understand user journeys visually

2. Installation

Step 1: Create a Clarity Project

  1. Visit https://clarity.microsoft.com

  2. Sign in using a Microsoft or Google account.

  3. Click Add New Project.

  4. Enter:

    • Project name

    • Website URL

  5. Copy your Project ID (example: abcd1234xy)

Step 2: Add Clarity Script to Next.js

For Pages Router (_app.js / _app.tsx)

import Script from "next/script";

export default function MyApp({ Component, pageProps }) {
return (
<>
<Script
id=“clarity-script”
strategy=“afterInteractive”
dangerouslySetInnerHTML={{
__html: `
(function(c,l,a,r,i,t,y){
c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
t=l.createElement(r);t.async=1;t.src=“https://www.clarity.ms/tag/”+i;
y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, “clarity“, “script“, “YOUR_PROJECT_ID“);
`,
}}
/>
<Component {…pageProps} />
</>
);
}

Replace YOUR_PROJECT_ID with the ID from your Clarity dashboard.

For App Router (app/layout.tsx)

import Script from "next/script";

export default function RootLayout({ children }) {
return (
<html>
<body>
<Script
id=“clarity-script”
strategy=“afterInteractive”
dangerouslySetInnerHTML={{
__html: `
(function(c,l,a,r,i,t,y){
c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
t=l.createElement(r);t.async=1;t.src=“https://www.clarity.ms/tag/”+i;
y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
})(window, document, “clarity“, “script“, “YOUR_PROJECT_ID“);
`,
}}
/>
{children}
</body>
</html>
);
}

3. Basic Usage

Verify Clarity Is Loaded

Open browser DevTools and run:

clarity

If Clarity is loaded, you should see:

ƒ clarity() { [native code] }

Track Custom Events (Tags)

You can attach custom tags to sessions for better filtering.

if (window.clarity) {
window.clarity("set", "feature_used", "search");
}

Example: Track a button click

<button
onClick={() => {
window.clarity?.("set", "cta_click", "signup_button");
}}
>
Sign Up
</button>

Track Logged-in Users

window.clarity("identify", userId);

This helps filter sessions by specific users (without exposing personal data).

Track Route Changes in SPA (Next.js)

import { useRouter } from "next/router";
import { useEffect } from "react";const useClarityTracking = () => {
const router = useRouter();useEffect(() => {
const handleRouteChange = (url: string) => {
if (window.clarity) {
window.clarity(“set”, “page”, url);
}
};

router.events.on(“routeChangeComplete”, handleRouteChange);
return () => {
router.events.off(“routeChangeComplete”, handleRouteChange);
};
}, [router]);
};

export default useClarityTracking;

Call this hook once in your _app.tsx.

4. Debugging & Validation

Enable Localhost Tracking

By default, Clarity does not record localhost.

  1. Open your Clarity project

  2. Go to Settings → Setup

  3. Under Tracking domains, enable:

    • localhost

    • 127.0.0.1

  4. Save changes

Verify Script in Network Tab

Open DevTools → Network → Filter clarity

You should see:

https://www.clarity.ms/tag/YOUR_PROJECT_ID

View Data in Dashboard

Go to:
Clarity Dashboard → Recordings / Heatmaps

You can filter by:

  • Device: Desktop / Mobile

  • Browser: WebView

  • URL

  • Custom tags

5. Using Clarity in Mobile Apps (Capacitor / WebView)

If your mobile app is built using Capacitor or WebView, Clarity works automatically because it tracks web content.

Tag Mobile Sessions

import { Capacitor } from "@capacitor/core";

if (window.clarity && Capacitor.isNativePlatform()) {
window.clarity(“set”, “platform”, “mobile_app”);
}

This allows filtering:

  • platform = mobile_app

  • OS: iOS / Android

⚠️ Note: Clarity does not support native UI session replay. It only tracks WebView content.

6. Privacy & Compliance

Microsoft Clarity is GDPR-friendly by default:

  • No personally identifiable information (PII)

  • No keystroke capture in input fields

  • Automatic masking of sensitive data

To manually mask fields:

<input data-clarity-mask="true" />

Analytics Result

With Microsoft Clarity, teams gain visual insight into real user behavior through session recordings and heatmaps. It becomes easy to:

  • Identify broken UI flows

  • Detect user frustration (rage clicks)

  • Understand drop-off points

  • Improve conversion rates

All without impacting application performance.

Conclusion

Microsoft Clarity is a powerful, completely free session replay and behavior analytics tool for React and Next.js applications. It provides unmatched visibility into how users interact with your product, helping teams optimize UX and debug real-world issues quickly.

When combined with traditional analytics tools like Google Analytics (GA4) or PostHog, Clarity becomes an essential part of a modern analytics stack—offering both quantitative metrics and qualitative user insights in one workflow.

You may also like

Leave a Reply