{"id":12490,"library":"vue-gtag","title":"Vue-gtag","description":"Vue-gtag is a Global Site Tag (gtag.js) plugin designed specifically for Vue 3 applications, facilitating the integration of Google Analytics, Google Ads, and Google Marketing Platform tracking. Currently at stable version 3.7.0, the library maintains an active release cadence, with frequent minor updates and bug fixes, often addressing dependency updates or small API refinements. It distinguishes itself by providing a deeply integrated, Vue-idiomatic API, including both a global plugin for straightforward application-wide setup and a composable `useGtag()` for fine-grained control within components. Key features include automatic pageview tracking when integrated with `vue-router` (now supporting both v4 and v5), comprehensive consent management functionalities, and support for all standard `gtag.js` commands (`event`, `config`, `set`). The library aims to simplify the often complex setup of Google tracking, allowing developers to leverage Google's robust analytics platform with minimal boilerplate in their Vue projects.","status":"active","version":"3.7.0","language":"javascript","source_language":"en","source_url":"https://github.com/MatteoGabriele/vue-gtag","tags":["javascript","google","google analytics","tracking","google tracking","vue-analytics","vue-gtag","gtag","gtag.js","typescript"],"install":[{"cmd":"npm install vue-gtag","lang":"bash","label":"npm"},{"cmd":"yarn add vue-gtag","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-gtag","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Vue 3 framework dependency.","package":"vue","optional":false},{"reason":"Optional for automatic pageview tracking. If omitted, pageviews must be tracked manually.","package":"vue-router","optional":true}],"imports":[{"note":"VueGtag is the default export representing the Vue plugin for `app.use()`.","wrong":"import { VueGtag } from 'vue-gtag'","symbol":"VueGtag","correct":"import VueGtag from 'vue-gtag'"},{"note":"The `useGtag` composable provides reactive access to gtag functions within Vue components.","wrong":"import useGtag from 'vue-gtag'","symbol":"useGtag","correct":"import { useGtag } from 'vue-gtag'"},{"note":"Use `import type` for type-only imports to ensure proper tree-shaking and avoid runtime issues.","wrong":"import { GtagOptions } from 'vue-gtag'","symbol":"GtagOptions","correct":"import type { GtagOptions } from 'vue-gtag'"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport App from './App.vue';\nimport { createRouter, createWebHistory } from 'vue-router';\nimport VueGtag from 'vue-gtag'; // The main plugin\nimport type { GtagOptions } from 'vue-gtag'; // Import types for clarity\n\n// 1. Setup Vue Router (optional, but recommended for pageview tracking)\nconst router = createRouter({\n  history: createWebHistory(),\n  routes: [\n    { path: '/', component: { template: '<div><h1>Home Page</h1><router-link to=\"/about\">Go to About</router-link></div>' } },\n    { path: '/about', component: { template: '<div><h1>About Page</h1><router-link to=\"/\">Go to Home</router-link></div>' } }\n  ],\n});\n\n// 2. Configure vue-gtag options\nconst gtagOptions: GtagOptions = {\n  appName: 'my-vue-app',\n  pageTrackerScreenviewEnabled: true, // Enables automatic pageview tracking\n  config: {\n    id: process.env.VUE_APP_GTAG_ID ?? 'G-XXXXXXXXXX', // Use an environment variable for your GA4 Measurement ID\n    params: {\n      send_page_view: true,\n    },\n  },\n  router, // Link router for automatic pageview tracking\n  // consent: {\n  //   granted: ['analytics_storage', 'ad_storage'],\n  //   denied: [],\n  //   default: { analytics_storage: 'denied', ad_storage: 'denied' }\n  // }\n};\n\n// 3. Create and configure Vue App\nconst app = createApp(App);\napp.use(router);\napp.use(VueGtag, gtagOptions);\n\napp.mount('#app');\n\n// App.vue (Example component using useGtag composable)\n<template>\n  <div>\n    <router-view></router-view>\n    <button @click=\"trackButtonClick\">Track Interaction</button>\n  </div>\n</template>\n\n<script setup lang=\"ts\">\nimport { useGtag } from 'vue-gtag';\nimport { onMounted } from 'vue';\n\nconst { event, consent } = useGtag();\n\nonMounted(() => {\n  console.log('App and gtag are ready.');\n  // Optionally set or update consent based on user interaction\n  // consent.update({ analytics_storage: 'granted', ad_storage: 'granted' });\n});\n\nfunction trackButtonClick() {\n  event('custom_button_click', {\n    event_category: 'engagement',\n    event_label: 'user_interaction',\n    value: Math.floor(Math.random() * 100) + 1,\n  });\n  console.log('Custom button click event sent.');\n}\n</script>","lang":"typescript","description":"Demonstrates `vue-gtag` installation with Vue Router for automatic pageview tracking and manual event sending via the `useGtag` composable."},"warnings":[{"fix":"Refer to the official vue-gtag documentation for Vue 3 migration guides. Update plugin initialization from `Vue.use()` to `app.use()` and replace `this.$gtag` with `useGtag()` composable.","message":"Vue-gtag v3 is exclusively for Vue 3 projects. Migration from v2 (for Vue 2) requires a complete rewrite of plugin initialization and API calls due to fundamental changes in the Vue 3 API.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"To enable automatic pageview tracking, ensure `vue-router` (v4 or v5) is installed and imported, then include `router` in your `VueGtag` plugin options: `app.use(VueGtag, { ..., router })`.","message":"While `vue-router` is an optional peer dependency, automatic pageview tracking will not function without it being installed and passed to the `vue-gtag` plugin options. Manual tracking for each page change would be required otherwise.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Carefully implement the `consent` option during plugin initialization or use the `consent.update()` method from `useGtag` in response to user choices. Ensure default consent states are set correctly according to regional regulations.","message":"Implementing Google's Consent Mode (V2) is critical for data privacy compliance. Incorrectly setting consent states (`analytics_storage`, `ad_storage`) can lead to data loss or legal non-compliance.","severity":"gotcha","affected_versions":">=3.5.0"},{"fix":"Communicate this limitation to stakeholders. While there's no direct fix within `vue-gtag`, server-side tracking (e.g., Google Tag Manager Server-Side) can mitigate some effects of client-side ad blocking.","message":"Ad blockers can prevent `gtag.js` scripts from loading and sending data to Google Analytics, resulting in incomplete or inaccurate analytics reports. This is a browser-level issue beyond the control of `vue-gtag`.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Always use `import` statements for `vue-gtag` in modern Vue CLI, Vite, or Nuxt 3 projects. If encountering issues in Node.js environments (like SSR), verify your build configuration supports ESM.","message":"Vue 3 applications are typically ESM-first. While `vue-gtag` v3.6.3 added 'node' export conditions, attempting to use CommonJS `require()` in an ESM context or vice-versa can lead to module resolution errors.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Double-check that the `id` property within the `config` object of your `VueGtag` options is a valid GA4 Measurement ID (e.g., 'G-XXXXXXXXXX'). Use environment variables for production IDs.","message":"Ensure the Google Analytics Measurement ID is correctly provided. A common mistake is to provide an invalid ID format or to omit the ID, leading to tracking failures.","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `app.use(VueGtag, ...)` is called before any components that use `useGtag()`. If using SSR, ensure `useGtag` calls are within `onMounted` or `nextTick` hooks to guarantee browser context.","cause":"The `useGtag()` composable was called before `vue-gtag` was properly initialized via `app.use()`, or the `gtag.js` script has not yet loaded.","error":"TypeError: Cannot read properties of undefined (reading 'event')"},{"fix":"Always use `import { useGtag } from 'vue-gtag'` for the composable. For the main plugin, use `import VueGtag from 'vue-gtag'` (default export).","cause":"Attempting to import `useGtag` (a named export) as a default export, or using CommonJS `require()` syntax in an ESM module.","error":"The requested module 'vue-gtag' does not provide an export named 'useGtag'."},{"fix":"Verify the `id` in `VueGtag` options matches your GA4 Measurement ID. Check browser console for `gtag.js` network errors. Inspect consent settings. Temporarily disable ad blockers for testing.","cause":"Incorrect Google Analytics ID, misconfigured `vue-gtag` options, ad blockers, or consent settings preventing data transmission.","error":"Google Analytics data is not appearing in reports."},{"fix":"Ensure `import VueGtag from 'vue-gtag'` is present and correct at the top of your `main.ts` (or equivalent entry file). Double-check for typos.","cause":"The `VueGtag` plugin was not imported correctly, or `app.use()` received an `undefined` value instead of the plugin.","error":"[Vue warn]: Failed to resolve plugin: VueGtag"}],"ecosystem":"npm"}