React Google Tag Manager Module

2.0.11 verified Sat Apr 25 auth: no javascript maintenance

react-gtm-module is a JavaScript library designed for React applications to streamline the integration of Google Tag Manager (GTM). It provides a programmatic API for managing the GTM snippet, initializing GTM with a specific container ID, and interacting with the `dataLayer` object. The current stable version is 2.0.11, last updated in November 2022. While the package remains functional, the original repository (alinemorelli/react-gtm) has seen limited activity since late 2020, with many pull requests and issues unaddressed. A community-maintained fork, `@sooro-io/react-gtm-module`, has emerged to provide continued development, TypeScript support, and additional features like CSP nonce and custom GTM script URLs. This original package (`react-gtm-module`) offers a straightforward abstraction for common GTM operations, simplifying custom `dataLayer` pushes, multiple `dataLayer` instances, and environment-specific GTM configurations without direct `window.dataLayer` manipulation.

Common errors

error Uncaught ReferenceError: TagManager is not defined ↓

cause The `TagManager` object was not imported or the import path is incorrect.

fix

Ensure import TagManager from 'react-gtm-module' is present at the top of your file before TagManager is used.

error Error: GTM ID is required ↓

cause The `gtmId` property was not provided or was empty in the `tagManagerArgs` object during `TagManager.initialize`.

fix

Pass a valid GTM container ID (e.g., GTM-XXXXXX) as the gtmId property to the TagManager.initialize function.

error GTM script returns 404 error in network requests ↓

cause The provided GTM ID is incorrect, or the GTM container associated with the ID has not been published in Google Tag Manager.

fix

Double-check your gtmId for typos. Ensure you have published at least one version of your GTM container in the Google Tag Manager interface.

Warnings

gotcha Ensure your `gtmId` is correct (e.g., `GTM-XXXXXX`). An incorrect ID can lead to a 404 error for the GTM script and no data being collected. ↓

fix Verify the GTM ID in your Google Tag Manager account settings and ensure it matches the ID passed to `TagManager.initialize`.

breaking The `events` argument behavior in `TagManager.initialize` had a bug fix in the `@sooro-io/react-gtm-module` fork, which constituted a breaking change from the original `react-gtm-module`. If relying on initial events pushed via `initialize`, test thoroughly or consider migrating to the fork. ↓

fix For the original `react-gtm-module`, carefully review the `events` functionality. For consistent and updated behavior, consider migrating to `@sooro-io/react-gtm-module` and consult its migration guide.

gotcha Avoid manually adding the GTM snippet to your `index.html` if using `react-gtm-module`. Doing so will result in double-tagging and potentially inaccurate data collection. ↓

fix Remove any manually placed GTM `<script>` tags from your `public/index.html` or equivalent file once `TagManager.initialize` is used.

gotcha If using a custom `dataLayerName`, ensure consistency. If `TagManager.initialize` is called with `dataLayerName: 'MyDataLayer'`, subsequent `TagManager.dataLayer` calls must also specify `dataLayerName: 'MyDataLayer'` to push to the correct `dataLayer` instance. ↓

fix Always pass the `dataLayerName` option to both `TagManager.initialize` and `TagManager.dataLayer` if you are using a custom `dataLayer` name.

deprecated The original `react-gtm-module` package has not been actively developed since late 2020. Consider using the community-maintained fork `@sooro-io/react-gtm-module` for ongoing support, new features (like CSP nonce and custom GTM script URLs), and TypeScript definitions. ↓

fix Migrate your project to use `@sooro-io/react-gtm-module` by uninstalling `react-gtm-module` and installing `@sooro-io/react-gtm-module`, then updating import paths.

Install

npm install react-gtm-module

yarn add react-gtm-module

pnpm add react-gtm-module

Imports

TagManager
wrong
```
import { TagManager } from 'react-gtm-module'
```
correct
```
import TagManager from 'react-gtm-module'
```
The library exports `TagManager` as a default export, not a named export. Ensure curly braces are not used.
TagManager.initialize
```
TagManager.initialize({ gtmId: 'GTM-XXXXXX' })
```
This function is used to inject the GTM script and optionally push initial `dataLayer` variables. It should typically be called once early in your application's lifecycle.
TagManager.dataLayer
wrong
```
window.dataLayer.push({ event: 'productClick', productId: '123' })
```
correct
```
TagManager.dataLayer({ dataLayer: { event: 'productClick', productId: '123' } })
```
Use `TagManager.dataLayer` for pushing events or data to the GTM `dataLayer` to maintain consistency and leverage the library's abstraction, especially when using a custom `dataLayerName`.

Quickstart

Initializes Google Tag Manager with a specified ID and initial `dataLayer` values. It also demonstrates how to push a custom event to the `dataLayer` after initialization using a button click, simulating common tracking scenarios.

import React from 'react';
import ReactDOM from 'react-dom/client';
import TagManager from 'react-gtm-module';

// Replace 'GTM-XXXXXX' with your actual Google Tag Manager ID
const GTM_ID = process.env.GTM_ID ?? 'GTM-DEFAULT'; 

const tagManagerArgs = {
  gtmId: GTM_ID,
  dataLayer: {
    userId: '12345',
    page: 'AppInitialization',
    status: 'logged_in',
  },
  events: {
    initEvent: 'gtm.js'
  }
};

TagManager.initialize(tagManagerArgs);

const App = () => {
  // Example of pushing an event after initialization
  const trackButtonClick = () => {
    TagManager.dataLayer({
      dataLayer: {
        event: 'buttonClick',
        category: 'Interaction',
        action: 'Click Me',
        label: 'Homepage Button'
      }
    });
    console.log('Button click event pushed to DataLayer');
  };

  return (
    <div>
      <h1>Welcome to the React GTM App</h1>
      <button onClick={trackButtonClick}>Track This Button</button>
      <p>GTM is initialized with ID: {GTM_ID}</p>
      <p>Check your GTM debug view or browser console for dataLayer pushes.</p>
    </div>
  );
};

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);