Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Hotjar
✓ import Hotjar from 'vue-hotjar'
✗ import { Hotjar } from 'vue-hotjar'
The plugin is exported as a default export.
Vue.use
✓ import Vue from 'vue'; import Hotjar from 'vue-hotjar'; Vue.use(Hotjar, { id: 'XXXXXXX' })
✗ import Hotjar from 'vue-hotjar'; new Vue({ el: '#app', render: h => h(App) }) // Hotjar not initialized
Hotjar must be initialized via `Vue.use()` for the plugin to register correctly.
$hj
✓ if (this.$hj) { this.$hj('event', 'user_action'); }
✗ this.$hj('event', 'user_action');
The `$hj` global property is only available for Vue 2.x.x and returns `false` if `isProduction` is set to `false`, requiring a check before use.
This quickstart demonstrates how to install `vue-hotjar`, initialize it with a Hotjar Site ID, and conditionally use the global `$hj` property for tracking custom events or identifying users.
import Vue from 'vue';
import Hotjar from 'vue-hotjar';
// Hotjar Site ID can be found at insights.hotjar.com under tracking.
// It's recommended to bind `isProduction` to your Node environment variable.
// snippetVersion defaults to 6 if not specified.
Vue.use(Hotjar, {
id: process.env.VUE_APP_HOTJAR_ID ?? '1234567',
isProduction: process.env.NODE_ENV === 'production',
snippetVersion: 6
});
// Example component where $hj can be used (Vue 2.x.x only)
export default {
methods: {
trackPurchase(userId, amount) {
if (this.$hj) {
this.$hj('identify', userId, {
email: 'user@example.com',
purchase_amount: amount,
ab_test: 'variant-B',
});
this.$hj('stateChange', '/purchase-complete');
}
}
}
};
Debug
Known issues
breakingThis `vue-hotjar` package is designed for Vue 2.x.x. For Vue 3.x.x projects, it offers only partial support, and users may encounter issues, particularly with TypeScript typings due to interface updates in Vue 3. A separate package, `vue-hotjar-next`, is available for full Vue 3 compatibility.fixFor Vue 3 projects, consider using `vue-hotjar-next` instead. If staying with `vue-hotjar` for Vue 3, be aware of potential typing conflicts and limited functionality.
affects: >=1.0.0 (when used with Vue 3)
gotchaThe `$hj` global property, which provides access to the Hotjar API, is only available if your Vue version is 2.x.x. It is explicitly disabled for Vue 3.0.0 and above for compatibility reasons.fixEnsure your project is running Vue 2.x.x to use the `$hj` global property. For Vue 3, you must use the `vue-hotjar-next` package or directly interact with `window.hj` if the plugin doesn't offer an alternative for Vue 3.
affects: >=1.0.0 (when used with Vue 3)
gotchaThe `$hj` global property will return `false` if the `isProduction` parameter is set to `false` during plugin initialization. This means any calls to `$hj` methods must be wrapped in a conditional check.fixAlways wrap `$hj` calls in a conditional statement, e.g., `if (this.$hj) { this.$hj('event', 'my_event'); }`, especially during development or when `isProduction` is false. affects: >=1.0.0
gotchaThe package has not been updated since June 2021. This might lead to compatibility issues with newer versions of Vue 2 (though less likely) or newer Hotjar SDK features/changes not explicitly covered by this plugin.fixBefore integrating, verify compatibility with your specific Vue 2 environment and ensure the Hotjar features you plan to use are supported by this older plugin. Consider alternatives or direct Hotjar script integration if this plugin's features are insufficient or outdated.
affects: >=1.4.0
Errors
Common errors & fixes
Cannot read property '$hj' of undefined
Attempting to access `this.$hj` in a Vue 3 component or when `isProduction` is `false` without a check. In Vue 3, `$hj` is not injected by this package. If `isProduction` is `false`, `$hj` is explicitly `false`.
fixFor Vue 2, ensure `isProduction` is `true` or wrap `$hj` calls in `if (this.$hj) { ... }`. For Vue 3, this package does not provide `$hj`. Use `vue-hotjar-next` for Vue 3 support, or directly interact with `window.hj` after Hotjar has loaded. TypeError: Cannot read properties of undefined (reading 'use')
This error typically indicates that `Vue` is not correctly imported or available when `Vue.use(Hotjar, ...)` is called, or an incorrect `Vue` instance is being used for initialization.
fixEnsure `import Vue from 'vue'` is at the top of your main application file and that you are using a Vue 2 application context for this plugin. Verify `vue` is correctly installed as a dependency.
Audit
Dependencies
vuerequiredRequired as a peer dependency for Vue plugin functionality.