Google Tag integration for Nuxt with support for Google Analytics 4, Google Ads and more.
- 🌻 Zero dependencies except Google's
gtag.js - 🛍️ Use Google Analytics 4, Google Ads and other products
- 🛎️ Supports Google Consent Mode v2
- 🤝 Manually initialize a Google tag
- 🔢 Supports multiple tag IDs
- 📯 Track events with composables
- 🏷️ Fully typed
gtag.jsAPI - 🦾 SSR-ready
npx nuxi@latest module add gtagAdd nuxt-gtag to the modules section of your Nuxt configuration and provide your Google tag ID (for multiple tag IDs, see below).
export default defineNuxtConfig({
modules: ['nuxt-gtag'],
gtag: {
id: 'G-XXXXXXXXXX'
}
})Done! The gtag.js script will be loaded and initialized client-side with your Google tag ID when the Nuxt application starts.
Note
Ensure that the Enhanced measurement feature is enabled to allow gtag.js to automatically track page changes based on browser history events in Nuxt.
To enable this feature:
- Go to the GA4 reporting view and click on “Admin”
- Select “Data Streams” under the “Property” column.
- Click on your web data stream.
- Next, toggle the switch button near “Enhanced measurement”.
All supported module options can be configured using the gtag key in your Nuxt configuration. An example of some of the options you can set:
export default defineNuxtConfig({
modules: ['nuxt-gtag'],
gtag: {
// Your primary Google tag ID
id: 'G-XXXXXXXXXX',
// Additional configuration for this tag ID
config: {
page_title: 'My Custom Page Title'
},
}
})If you want to send data to multiple destinations, you can add more than one Google tag ID to your Nuxt configuration in the tags module option. Pass a string (single tag ID) or an object (tag ID with additional configuration) to the tags array.
The following example shows how to load a second Google tag that is connected to a Floodlight destination:
export default defineNuxtConfig({
modules: ['nuxt-gtag'],
gtag: {
tags: [
// Google Ads and GA4, with additional configuration
{
id: 'G-XXXXXXXXXX',
config: {
page_title: 'My Custom Page Title'
}
},
// Second Google tag ID for Floodlight
'DC-ZZZZZZZZZZ'
]
}
})Instead of hard-coding your Google tag ID in your Nuxt configuration, you can set your desired option in your project's .env file, leveraging automatically replaced public runtime config values by matching environment variables at runtime.
# Overwrites the `gtag.id` module option
NUXT_PUBLIC_GTAG_ID=G-XXXXXXXXXXWith this setup, you can omit the gtag key in your Nuxt configuration if you only intend to set the Google tag ID.
Tip
Follows the Google Consent Mode v2 specification.
Set a default value for each consent type you are using. By default, no consent mode values are set.
The following example sets multiple consent mode parameters to denied by default:
export default defineNuxtConfig({
modules: ['nuxt-gtag'],
gtag: {
id: 'G-XXXXXXXXXX',
initCommands: [
// Setup up consent mode
['consent', 'default', {
ad_user_data: 'denied',
ad_personalization: 'denied',
ad_storage: 'denied',
analytics_storage: 'denied',
wait_for_update: 500,
}]
]
}
})After a user indicates their consent choices, update relevant parameters to granted:
function allConsentGranted() {
const { gtag } = useGtag()
gtag('consent', 'update', {
ad_user_data: 'granted',
ad_personalization: 'granted',
ad_storage: 'granted',
analytics_storage: 'granted'
})
}
function consentGrantedAdStorage() {
const { gtag } = useGtag()
gtag('consent', 'update', {
ad_storage: 'granted'
})
}
// Invoke the consent function when a user interacts with your banner
consentGrantedAdStorage() // Or `allConsentGranted()`For even more control than the consent mode, you can delay the loading of the gtag.js script until the user has granted consent to your privacy policy. Set the enabled option to false to prevent loading the gtag.js script until you manually enable it:
export default defineNuxtConfig({
modules: ['nuxt-gtag'],
gtag: {
enabled: false,
id: 'G-XXXXXXXXXX'
}
})To manually load the Google tag script, i.e. after the user has accepted your privacy policy, you can use the initialize method destructurable from useGtag:
<script setup lang="ts">
const { gtag, initialize } = useGtag()
</script>
<template>
<button @click="initialize()">
Grant Consent
</button>
</template>You can even leave the Google tag ID in your Nuxt config blank and set it dynamically later in your application by passing your ID as the first argument to initialize. This is especially useful if you want to use a custom ID for each user or if your app manages multiple tenants.
const { gtag, initialize } = useGtag()
function acceptTracking() {
initialize('G-XXXXXXXXXX')
}| Option | Type | Default | Description |
|---|---|---|---|
enabled |
boolean |
true |
Whether to initialize the Google tag script immediately after the page has loaded. |
id |
string |
undefined |
The Google tag ID to initialize. |
initCommands |
See initCommands of GoogleTagOptions |
[] |
Commands to be executed when the Google tag ID is initialized. |
config |
See config of GoogleTagOptions |
{} |
The configuration parameters to be passed to gtag.js on initialization. |
tags |
string[] | GoogleTagOptions[] |
[] |
Multiple Google tag IDs to initialize for sending data to different destinations. |
loadingStrategy |
'async' | 'defer' |
'defer' |
The loading strategy to be used for the gtag.js script. |
url |
string |
Source | The URL to the gtag.js script. Use this option to load the script from a custom URL. |
As with other composables in the Nuxt 3 ecosystem, they are auto-imported and can be used in your application's components.
The SSR-safe useGtag composable provides access to:
- The
gtag.jsinstance - The
initializemethod - The
disableAnalyticsmethod - The
enableAnalyticsmethod
It can be used as follows:
// Each method is destructurable from the composable and can be
// used on the server and client-side
const { gtag, initialize, disableAnalytics, enableAnalytics } = useGtag()Type Declarations
function useGtag(): {
gtag: Gtag
initialize: (id?: string) => void
disableAnalytics: (id?: string) => void
enableAnalytics: (id?: string) => void
}The gtag function is the main interface to the gtag.js instance and can be used to run every gtag.js command.
Note
Since the gtag.js instance is available in the client only, any gtag() calls executed on the server will have no effect.
Example
The following event command fires the event screen_view with two parameters: app_name and screen_name.
const { gtag } = useGtag()
// SSR-ready
gtag('event', 'screen_view', {
app_name: 'My App',
screen_name: 'Home'
})Type Declarations
interface GtagCommands {
config: [targetId: string, config?: ControlParams | EventParams | ConfigParams | CustomParams]
set: [targetId: string, config: CustomParams | boolean | string] | [config: CustomParams]
js: [config: Date]
event: [eventName: EventNames | (string & {}), eventParams?: ControlParams | EventParams | CustomParams]
get: [
targetId: string,
fieldName: FieldNames | string,
callback?: (field?: string | CustomParams) => any,
]
consent: [consentArg: ConsentArg | (string & {}), consentParams: ConsentParams]
}
const gtag: {
<Command extends keyof GtagCommands>(command: Command, ...args: GtagCommands[Command]): void
}If you want to manually manage the initialization of the Google tag script, i.e. for GDPR compliance, you can use the initialize method to inject the gtag.js script to the document's head after the user has accepted your privacy policy. Make sure to set enabled to false in the Nuxt module for this to work.
The function accepts an optional ID in case you want to initialize a custom Google tag ID, which isn't set in the module options.
Example
const { initialize } = useGtag()
// Load the `gtag.js` script and initialize all tag IDs from the module options
initialize()Tip
Although this method is SSR-safe, the gtag.js script will be loaded in the client only. Make sure to run this method in the client.
Type Declarations
function initialize(id?: string): voidIn some cases, it may be necessary to disable Google Analytics without removing the Google tag. For example, you might want to provide users with the option to opt out of tracking.
The gtag.js library includes a window property that, toggles gtag.js from sending data to Google Analytics. When Google Analytics attempts to set a cookie or send data back to the Google Analytics servers, this property is checked to determine whether to allow the action.
Example
const { disableAnalytics } = useGtag()
disableAnalytics()Type Declarations
function disableAnalytics(id?: string): voidThe enableAnalytics method is the counterpart to disableAnalytics and can be used to re-enable Google Analytics after it has been disabled.
Example
const { enableAnalytics } = useGtag()
enableAnalytics()Type Declarations
function enableAnalytics(id?: string): voidTrack your defined goals by passing the following parameters:
- The name of the recommended or custom event.
- A collection of parameters that provide additional information about the event (optional).
Note
This composable is SSR-ready. But since the gtag.js instance is available in the client only, executing the composable on the server will have no effect.
Example
For example, the following is an event called login with a parameter method:
// Tracks the `login` event
useTrackEvent('login', {
method: 'Google'
})Type Declarations
function useTrackEvent(
eventName: EventNames | (string & {}),
eventParams?: ControlParams | EventParams | CustomParams
): void- Clone this repository
- Enable Corepack using
corepack enable - Install dependencies using
pnpm install - Run
pnpm run dev:prepare - Start development server using
pnpm run dev
- Maronbeere for his logo pixel art.
- Junyoung Choi and Lucas Akira Uehara for their Google
gtag.jsAPI type definitions
MIT License © 2023-PRESENT Johann Schopplich
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent