@jwiedeman/gtm-kit-astro
v1.1.6
Published
Astro components and helpers for GTM Kit - Google Tag Manager integration with View Transitions support.
Maintainers
jwiedemanReadme
@jwiedeman/gtm-kit-astro
Astro components and helpers for Google Tag Manager. Supports View Transitions API.
The Astro integration for GTM Kit - includes ready-to-use components and client-side helpers for page tracking.
Installation
npm install @jwiedeman/gtm-kit @jwiedeman/gtm-kit-astroyarn add @jwiedeman/gtm-kit @jwiedeman/gtm-kit-astropnpm add @jwiedeman/gtm-kit @jwiedeman/gtm-kit-astroQuick Start
Option 1: Use the GtmHead Component (Recommended)
The easiest way to add GTM to your Astro site:
---
// src/layouts/Layout.astro
import { GtmHead } from '@jwiedeman/gtm-kit-astro/components';
---
<html>
<head>
<GtmHead
containers="GTM-XXXXXX"
enablePageTracking
/>
</head>
<body>
<slot />
</body>
</html>Option 2: Use Individual Components
For more control, use the script and noscript components separately:
---
// src/layouts/Layout.astro
import { GtmScript, GtmNoScript } from '@jwiedeman/gtm-kit-astro/components';
---
<html>
<head>
<GtmScript containers="GTM-XXXXXX" />
</head>
<body>
<GtmNoScript containers="GTM-XXXXXX" />
<slot />
</body>
</html>Option 3: Client-Side API
For programmatic control:
---
// src/layouts/Layout.astro
---
<html>
<head>
<!-- Your head content -->
</head>
<body>
<slot />
<script>
import { initGtm, push, setupPageTracking } from '@jwiedeman/gtm-kit-astro';
initGtm({ containers: 'GTM-XXXXXX' });
setupPageTracking();
// Push custom events
push({ event: 'page_loaded', page_type: 'home' });
</script>
</body>
</html>Features
| Feature | Description | | -------------------- | --------------------------------------------------------- | | View Transitions | Automatic page tracking with Astro's View Transitions API | | Zero Config | Works out of the box with sensible defaults | | Astro 3, 4, 5 | Compatible with all modern Astro versions | | TypeScript | Full type definitions included | | Consent Mode v2 | Built-in GDPR compliance support | | SSR Safe | Works with static and SSR modes |
Components
<GtmHead />
All-in-one component for the <head> section. Includes script loading, consent setup, and optional page tracking.
<GtmHead
containers="GTM-XXXXXX"
enablePageTracking
defaultConsent={{
ad_storage: 'denied',
analytics_storage: 'denied'
}}
pageViewEventName="page_view"
/>Props
| Prop | Type | Default | Description |
| -------------------- | -------------------- | ---------------------------------- | ------------------------------- |
| containers | string \| string[] | Required | GTM container ID(s) |
| host | string | https://www.googletagmanager.com | Custom GTM host |
| dataLayerName | string | dataLayer | Custom dataLayer name |
| defaultConsent | ConsentState | - | Default consent state |
| enablePageTracking | boolean | false | Enable automatic page tracking |
| pageViewEventName | string | page_view | Custom page view event name |
| scriptAttributes | object | - | Script attributes (nonce, etc.) |
<GtmScript />
Generates GTM script tags for the <head>.
<GtmScript
containers="GTM-XXXXXX"
scriptAttributes={{ nonce: 'abc123' }}
/><GtmNoScript />
Generates noscript iframe fallback for the <body>.
<GtmNoScript containers="GTM-XXXXXX" />Client-Side API
initGtm(options)
Initialize GTM on the client side.
import { initGtm } from '@jwiedeman/gtm-kit-astro';
initGtm({
containers: 'GTM-XXXXXX',
dataLayerName: 'dataLayer'
});push(data)
Push data to the dataLayer.
import { push } from '@jwiedeman/gtm-kit-astro';
push({ event: 'button_click', button_id: 'cta-main' });setupPageTracking(options)
Set up automatic page view tracking. Works with Astro's View Transitions.
import { setupPageTracking } from '@jwiedeman/gtm-kit-astro';
setupPageTracking({
eventName: 'page_view' // Optional, defaults to 'page_view'
});setupViewTransitions(options)
Alias for setupPageTracking. Sets up tracking for View Transitions API.
import { setupViewTransitions } from '@jwiedeman/gtm-kit-astro';
setupViewTransitions({ eventName: 'virtual_page_view' });trackPageView(options)
Manually track a page view.
import { trackPageView } from '@jwiedeman/gtm-kit-astro';
trackPageView({
eventName: 'page_view',
pagePath: '/custom-path',
pageTitle: 'Custom Title'
});Consent Mode v2 (GDPR)
Setting Default Consent
<GtmHead
containers="GTM-XXXXXX"
defaultConsent={{
ad_storage: 'denied',
ad_user_data: 'denied',
ad_personalization: 'denied',
analytics_storage: 'denied'
}}
/>Updating Consent After User Choice
import { updateConsent } from '@jwiedeman/gtm-kit-astro';
// User accepts analytics
updateConsent({
analytics_storage: 'granted'
});
// User accepts all
updateConsent({
ad_storage: 'granted',
ad_user_data: 'granted',
ad_personalization: 'granted',
analytics_storage: 'granted'
});View Transitions Integration
GTM Kit automatically tracks page views when using Astro's View Transitions. Just enable page tracking:
---
import { GtmHead } from '@jwiedeman/gtm-kit-astro/components';
import { ViewTransitions } from 'astro:transitions';
---
<html>
<head>
<ViewTransitions />
<GtmHead
containers="GTM-XXXXXX"
enablePageTracking
/>
</head>
<body>
<slot />
</body>
</html>Page views are automatically tracked on:
- Initial page load
- Client-side navigation via View Transitions
- Browser back/forward navigation
Multiple Containers
<GtmHead
containers={['GTM-XXXXXX', 'GTM-YYYYYY']}
enablePageTracking
/>CSP (Content Security Policy)
<GtmHead
containers="GTM-XXXXXX"
scriptAttributes={{ nonce: 'your-nonce-value' }}
/>Requirements
- Astro 3.0+, 4.0+, or 5.0+
@jwiedeman/gtm-kit(peer dependency)
Related Packages
- Core: @jwiedeman/gtm-kit (required)
Support
Have a question, found a bug, or need help?
Open an issue on GitHub — we're actively maintaining this project and respond quickly.
License
MIT