Clarity
Microsoft Clarity records sessions and generates heatmaps for your site.
Nuxt Config Setup
Add this to your nuxt.config.ts to load Clarity globally. Alternatively you can use the useScriptClarity composable for more control.
export default defineNuxtConfig({
scripts: {
registry: {
clarity: {
id: 'xxxxxxxxxx',
trigger: 'onNuxtReady',
}
}
}
})This config automatically enables first-party mode (bundle + proxy). See below to customise.
useScriptClarity()
The useScriptClarity composable lets you have fine-grain control over when and how Clarity is loaded on your site.
const { proxy } = useScriptClarity()
proxy.clarity('event', 'conversion')Please follow the Registry Scripts guide to learn more about advanced usage.
First-Party Mode: Privacy Focused Proxy
No extra config needed. The script is bundled from your domain (faster loads, no extra DNS lookup) and runtime requests are reverse-proxied through your server with automatic anonymisation (user IPs stay hidden from Clarity, works with ad blockers). Learn more.
export default defineNuxtConfig({
scripts: {
// ✅ First-party mode: bundled + proxied
registry: {
clarity: {
id: 'xxxxxxxxxx',
trigger: 'onNuxtReady',
},
},
},
})Example
Using Clarity in a component with the proxy to send events .
<script setup lang="ts">
const { proxy } = useScriptClarity()
// noop in development, ssr
// just works in production, client
function handleAction() {
proxy.clarity('event', 'conversion')
}
</script>
<template>
<div>
<button @click="handleAction">
Send Event
</button>
</div>
</template>idstring required The Clarity token.
defaultConsentboolean | Record<string, string>Default consent state applied before Clarity starts. - `boolean` - enable / disable cookies. - `Record<string, string>` - advanced consent vector (see Clarity docs).
Consent mode
The defaultConsent option and consent.set() wrap Clarity's deprecated Consent API V1. Microsoft documents that API with a boolean value (or no value to grant consent). Although the current Nuxt Scripts schema also accepts Record<string, string>, Clarity does not document an object payload for V1.
<script setup lang="ts">
const { consent } = useScriptClarity({
id: 'YOUR_PROJECT_ID',
defaultConsent: false, // disable cookies until user opts in
})
function acceptAnalytics() {
consent.set(true)
}
</script>
For new integrations, call Consent API V2 through the script proxy, using Clarity's case-sensitive category names:
const { proxy } = useScriptClarity({
id: 'YOUR_PROJECT_ID',
})
proxy.clarity('consentv2', {
ad_Storage: 'denied',
analytics_Storage: 'denied',
})
// Update after the user grants consent.
proxy.clarity('consentv2', {
ad_Storage: 'granted',
analytics_Storage: 'granted',
})
defaultConsent and consent.set() do not issue consentv2 commands. See Clarity Consent API V2 for the current API.