How to Set Up Microsoft Clarity in Next.js (Free Heatmaps & Session Recordings)

Most analytics tools tell you what users do — pageviews, bounce rates, conversion funnels. Microsoft Clarity shows you how they do it — with free heatmaps and session recordings.

It's completely free, has no traffic limits, and takes 5 minutes to add to a Next.js app. Here's how.

What Is Microsoft Clarity?

Microsoft Clarity is a free analytics tool that provides:

Session recordings — Watch real users navigate your app
Heatmaps — See where users click, scroll, and hover
Dead click detection — Find UI elements users click that don't do anything
Rage click detection — Identify frustrating areas where users click repeatedly
Scroll depth — See how far users scroll on each page
Insights dashboard — Automated insights about user behavior

The best part? It's 100% free with no traffic limits. Google Analytics tells you numbers. Clarity shows you the actual user experience.

Step 1: Create a Clarity Project

Go to clarity.microsoft.com
Sign in with your Microsoft, Google, or Facebook account
Click New Project
Enter your project name and website URL
Copy your Project ID — it's the alphanumeric string shown in the setup instructions (e.g., abc123xyz)

Step 2: Add the Environment Variable

Add your Clarity Project ID to .env.local:

NEXT_PUBLIC_MICROSOFT_CLARITY=your_project_id_here

Note the NEXT_PUBLIC_ prefix — this is required because the Clarity script runs in the browser (client-side).

Step 3: Create the Clarity Provider Component

Create a React component that loads the Clarity tracking script:

// src/lib/providers.tsx (or a dedicated clarity.tsx file)
"use client";

import Script from "next/script";

export function MicrosoftClarityProvider() {
  const clarityTag = process.env.NEXT_PUBLIC_MICROSOFT_CLARITY;
  const isDev = process.env.NEXT_PUBLIC_ENV === "dev";

  if (!clarityTag || isDev) {
    return null;
  }

  return (
    <Script
      id="microsoft-clarity-init"
      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", "${clarityTag}");
        `,
      }}
    />
  );
}

Key things happening here:

strategy="afterInteractive" — The script loads after the page becomes interactive, so it doesn't block rendering or slow down your app
Dev mode check — Clarity is skipped in development so you don't pollute your data with local testing sessions
Null check — If no Project ID is set, nothing loads. No errors, no broken pages.

Step 4: Add It to Your Root Layout

Include the component in your root layout so it loads on every page:

// src/app/layout.tsx
import { MicrosoftClarityProvider } from "@/lib/providers";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <MicrosoftClarityProvider />
        {children}
      </body>
    </html>
  );
}

That's it. Deploy your app, and Clarity will start recording sessions automatically.

Step 5: Verify It's Working

Deploy your app (or test in production mode locally with npm run build && npm start)
Visit your site in a browser
Go to your Clarity dashboard
Within a few minutes, you should see your first session appear

If you don't see data, check:

The NEXT_PUBLIC_MICROSOFT_CLARITY env var is set in your deployment environment (Vercel, Netlify, etc.)
You're not running in dev mode (the component returns null in dev)
There are no ad blockers active in your browser

What to Look for in Clarity

Once data starts flowing, here's what to pay attention to:

Session Recordings

Watch real users navigate your app. Look for:

Where they get stuck — Pauses, back-and-forth navigation
Where they drop off — The last page before they leave
Unexpected paths — Users finding features in ways you didn't intend

Heatmaps

Click heatmaps — Are users clicking your CTAs? Or are they clicking non-interactive elements?
Scroll heatmaps — Is your most important content above the fold? How far do users scroll?

Rage Clicks & Dead Clicks

Clarity automatically flags these. Rage clicks mean users are frustrated. Dead clicks mean your UI is misleading. Both are bugs to fix.

Combining with Google Analytics

Clarity and Google Analytics complement each other perfectly:

Tool	What It Tells You
Google Analytics	How many users, where they come from, conversion rates
Microsoft Clarity	How users behave, what frustrates them, why they leave

Use GA for the numbers, Clarity for the "why." Both are free.

The Faster Way: Use NextUpKit

NextUpKit ships with Microsoft Clarity already integrated:

MicrosoftClarityProvider component — Already built in src/lib/providers.tsx
Environment variable — NEXT_PUBLIC_MICROSOFT_CLARITY defined in .env.example
Dev mode detection — Automatically disabled in development
Google Analytics too — Both analytics tools are preconfigured

Plus authentication, payments, database, email, and everything else you need for a SaaS. All free and open source.

git clone https://github.com/nextupkit/nextupkit.git
cd nextupkit
npm install
# Add NEXT_PUBLIC_MICROSOFT_CLARITY=your_id to .env.local
npm run dev

Why Every SaaS Should Use Clarity

If you're building a SaaS, you need to understand how users interact with your product. Most founders rely on gut feeling or customer complaints. Clarity gives you the actual footage.

It's free. It takes 5 minutes to set up. There's no reason not to use it.

Get NextUpKit with Clarity preconfigured →