Hotjar
Hotjar combines session recordings, heatmaps, surveys, and user-feedback tools.
Nuxt Config Setup
Add this to your nuxt.config.ts to load Hotjar globally. Alternatively you can use the useScriptHotjar composable for more control.
export default defineNuxtConfig({
scripts: {
registry: {
hotjar: {
id: '1234567',
trigger: 'onNuxtReady',
}
}
}
})This config automatically enables first-party mode (bundle + proxy). See below to customise.
useScriptHotjar()
The useScriptHotjar composable lets you have fine-grain control over when and how Hotjar is loaded on your site.
const { proxy } = useScriptHotjar()
proxy.hj('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 Hotjar, works with ad blockers). Learn more.
export default defineNuxtConfig({
scripts: {
// ✅ First-party mode: bundled + proxied
registry: {
hotjar: {
id: '1234567',
trigger: 'onNuxtReady',
},
},
},
})Example
Using Hotjar in a component with the proxy to send events .
<script setup lang="ts">
const { proxy } = useScriptHotjar()
// noop in development, ssr
// just works in production, client
function handleAction() {
proxy.hj('event', 'conversion')
}
</script>
<template>
<div>
<button @click="handleAction">
Send Event
</button>
</div>
</template>Events and user attributes
Calls made through proxy.hj queue until the script is ready. Send an event when you want to filter recordings or heatmaps by a specific action:
const { proxy } = useScriptHotjar()
function recordSignup() {
proxy.hj('event', 'signup_completed')
}
Hotjar's Events API reference lists the event-name restrictions and filtering limits. Events do not accept properties.
Use the Identify API for user attributes instead:
const { proxy } = useScriptHotjar()
proxy.hj('identify', user.id, {
plan: user.plan,
})
Before sending attributes, review Hotjar's Identify API privacy and data guidance. Prefer a stable internal ID over an email address, and send only the fields you need.
idnumber required Your Hotjar Site ID.
svnumber = 6The Hotjar snippet version.