Clarity
Clarity by Microsoft is a screen recorder and heatmap tool that helps you understand how users interact with your website.
Nuxt Scripts provides a registry script composable useScriptClarity to easily integrate Clarity in your Nuxt app.
The simplest way to load Clarity globally in your Nuxt App is to use Nuxt config. Alternatively you can directly use the useScriptClarity composable.
Loading Globally
If you don't plan to send custom events you can use the Environment overrides to disable the script in development.
export default defineNuxtConfig({
scripts: {
registry: {
clarity: {
id: 'YOUR_ID'
}
}
}
})
useScriptClarity
The useScriptClarity composable lets you have fine-grain control over when and how Clarity is loaded on your site.
const { proxy } = useScriptClarity({
id: 'YOUR_ID'
})
// example
proxy.clarity("identify", "custom-id", "custom-session-id", "custom-page-id", "friendly-name")
Please follow the Registry Scripts guide to learn more about advanced usage.
ClarityApi
type ClarityFunctions = ((fn: 'start', options: { content: boolean, cookies: string[], dob: number, expire: number, projectId: string, upload: string }) => void)
& ((fn: 'identify', id: string, session?: string, page?: string, userHint?: string) => Promise<{
id: string
session: string
page: string
userHint: string
}>)
& ((fn: 'consent') => void)
& ((fn: 'set', key: any, value: any) => void)
& ((fn: 'event', value: any) => void)
& ((fn: 'upgrade', upgradeReason: any) => void)
& ((fn: string, ...args: any[]) => void)
export interface ClarityApi {
clarity: ClarityFunctions & {
q: any[]
v: string
}
}
Config Schema
You must provide the options when setting up the script for the first time.
export const ClarityOptions = object({
/**
* The Clarity token.
*/
id: pipe(string(), minLength(10)),
})
Example
Using Clarity only in production while using clarity to send a conversion event.
<script setup lang="ts">
const { proxy } = useScriptClarity()
// noop in development, ssr
// just works in production, client
function sendConversion() {
proxy.clarity('event', 'conversion')
}
</script>
<template>
<div>
<button @click="sendConversion">
Send Conversion
</button>
</div>
</template>