In the ground since Sun Nov 09 2025
Last watered inSun Nov 09 2025
Microsoft Clarity
Microsoft Clarity is a free analytics tool that helps you understand how users interact with your website through session recordings, heatmaps, and user insights.
Adding Clarity to Next.js Projects
The Recommended Way
Use Next.js's Script component with the afterInteractive strategy in your root layout:
1import Script from "next/script";
2
3export default function RootLayout({ children }) {
4 return (
5 <html>
6 <body>
7 <Script
8 id="microsoft-clarity"
9 strategy="afterInteractive"
10 dangerouslySetInnerHTML={{
11 __html: `
12 (function(c,l,a,r,i,t,y){
13 c[a]=c[a]||function(){(c[a].q=c[a].q||[]).push(arguments)};
14 t=l.createElement(r);t.async=1;t.src="https://www.clarity.ms/tag/"+i;
15 y=l.getElementsByTagName(r)[0];y.parentNode.insertBefore(t,y);
16 })(window, document, "clarity", "script", "YOUR_PROJECT_ID");
17 `,
18 }}
19 />
20 {children}
21 </body>
22 </html>
23 );
24}
Do's and Don'ts
✅ Do's
1. Use the Script Component
- Always use Next.js's Script component, never regular <script> tags
- This ensures proper hydration and optimal loading
2. Use the afterInteractive Strategy
- Loads the script after the page becomes interactive
- Prevents blocking the initial page render
- Balances analytics accuracy with performance
3. Place in Root Layout
- Add Clarity to app/layout.tsx to track all pages
- Ensures consistent tracking across your entire site
4. Use dangerouslySetInnerHTML for Inline Scripts
- Required for inline executable JavaScript
- Safe when the script content is from a trusted source (Microsoft's official docs)
- The name is intentionally scary, but it's the correct approach here
5. Add a Unique id Prop
- Always include id="microsoft-clarity" on the Script component
- Prevents duplicate script injections during development
❌ Don'ts
1. Don't Use npm Packages
1// ❌ Wrong - Unnecessary dependency
2import Clarity from '@microsoft/clarity';
3Clarity.init("PROJECT_ID");
The inline script approach is simpler and doesn't add dependencies.
2. Don't Try to Initialize on the Server
1// ❌ Wrong - Server-side code
2if (typeof window !== 'undefined') {
3 Clarity.init("PROJECT_ID");
4}
This won't work in Next.js server components. Always use the Script component.
3. Don't Use beforeInteractive Strategy
1// ❌ Wrong - Blocks page rendering
2<Script strategy="beforeInteractive" ... />
Analytics should never block your page from loading.
4. Don't Put Scripts from User Input
1// ❌ DANGEROUS - Never do this
2<Script dangerouslySetInnerHTML={{ __html: userProvidedScript }} />
Only use dangerouslySetInnerHTML with hardcoded, trusted scripts.
5. Don't Use Regular Script Tags
1// ❌ Wrong - Breaks React hydration
2<script type="text/javascript">
3 {/* Clarity code */}
4</script>
Always use Next.js's Script component for third-party scripts.
Why dangerouslySetInnerHTML?
The name is intentionally scary to make developers think twice, but it's safe for analytics scripts because:
- ✅ You control the script content (from Microsoft's official docs)
- ✅ It's hardcoded in your source code, not from user input
- ✅ The script URL points to Microsoft's trusted CDN
- ✅ React normally escapes all content to prevent XSS attacks, but analytics scripts need to execute as-is
Alternative: External Script
If you prefer to avoid dangerouslySetInnerHTML, you can use the direct script URL:
1<Script
2 src="https://www.clarity.ms/tag/YOUR_PROJECT_ID"
3 strategy="afterInteractive"
4/>
However, Microsoft's recommended wrapper function (using dangerouslySetInnerHTML) ensures better async loading and is the preferred approach.
Getting Your Project ID
- Sign up at clarity.microsoft.com
- Create a new project
- Copy your project ID from the setup page
- Replace YOUR_PROJECT_ID in the script with your actual ID
What Clarity Tracks
- Session Recordings: Watch real user sessions to see how they navigate your site
- Heatmaps: See where users click, scroll, and focus their attention
- Insights: Identify rage clicks, dead clicks, and excessive scrolling
- Performance: No impact on page load times - completely free and unlimited
Privacy Considerations
Clarity automatically masks sensitive information like:
- Email addresses
- Phone numbers
- Credit card numbers
- Passwords
Always review your site's privacy policy and ensure compliance with GDPR/CCPA when using analytics tools.