{"id":15033,"library":"vue-hotjar","title":"Vue Hotjar Plugin","description":"Vue Hotjar is a plugin designed for easy integration of the Hotjar analytics and feedback platform into Vue.js projects. It simplifies the process of adding the Hotjar tracking code and provides a global Vue property, `$hj`, to interact with Hotjar's API (e.g., Identify API, stateChange, virtual page views). The package is currently at version 1.4.0, with its last update in June 2021. Its primary differentiators include environment-based tracking activation/deactivation and a streamlined interface to the Hotjar API within Vue instances. However, it offers only partial support for Vue 3, with known issues regarding TypeScript typings, and the `$hj` global property is exclusively available for Vue 2.x.x versions. A separate `vue-hotjar-next` package exists for full Vue 3 support, indicating this package is primarily for Vue 2 applications.","status":"maintenance","version":"1.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/henk-badenhorst/vue-hotjar","tags":["javascript","vue","plugin","hotjar","analytics","typescript"],"install":[{"cmd":"npm install vue-hotjar","lang":"bash","label":"npm"},{"cmd":"yarn add vue-hotjar","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-hotjar","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for Vue plugin functionality.","package":"vue","optional":false}],"imports":[{"note":"The plugin is exported as a default export.","wrong":"import { Hotjar } from 'vue-hotjar'","symbol":"Hotjar","correct":"import Hotjar from 'vue-hotjar'"},{"note":"Hotjar must be initialized via `Vue.use()` for the plugin to register correctly.","wrong":"import Hotjar from 'vue-hotjar'; new Vue({ el: '#app', render: h => h(App) }) // Hotjar not initialized","symbol":"Vue.use","correct":"import Vue from 'vue'; import Hotjar from 'vue-hotjar'; Vue.use(Hotjar, { id: 'XXXXXXX' })"},{"note":"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.","wrong":"this.$hj('event', 'user_action');","symbol":"$hj","correct":"if (this.$hj) { this.$hj('event', 'user_action'); }"}],"quickstart":{"code":"import Vue from 'vue';\nimport Hotjar from 'vue-hotjar';\n\n// Hotjar Site ID can be found at insights.hotjar.com under tracking.\n// It's recommended to bind `isProduction` to your Node environment variable.\n// snippetVersion defaults to 6 if not specified.\nVue.use(Hotjar, {\n  id: process.env.VUE_APP_HOTJAR_ID ?? '1234567',\n  isProduction: process.env.NODE_ENV === 'production',\n  snippetVersion: 6\n});\n\n// Example component where $hj can be used (Vue 2.x.x only)\nexport default {\n  methods: {\n    trackPurchase(userId, amount) {\n      if (this.$hj) {\n        this.$hj('identify', userId, {\n          email: 'user@example.com',\n          purchase_amount: amount,\n          ab_test: 'variant-B',\n        });\n        this.$hj('stateChange', '/purchase-complete');\n      }\n    }\n  }\n};","lang":"typescript","description":"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."},"warnings":[{"fix":"For 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.","message":"This `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.","severity":"breaking","affected_versions":">=1.0.0 (when used with Vue 3)"},{"fix":"Ensure 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.","message":"The `$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.","severity":"gotcha","affected_versions":">=1.0.0 (when used with Vue 3)"},{"fix":"Always 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.","message":"The `$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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Before 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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.4.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"For 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.","cause":"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`.","error":"Cannot read property '$hj' of undefined"},{"fix":"Ensure `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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'use')"}],"ecosystem":"npm"}