React Google Analytics 4 Wrapper

Common errors

• ReferenceError: require is not defined

  cause Attempting to import `react-ga4` using CommonJS `require()` syntax in a project configured for ES Modules, or after upgrading to v3.0.1+.
  fix Change your import statement from `const ReactGA = require('react-ga4');` to `import ReactGA from 'react-ga4';`.

• TypeError: ReactGA.pageview is not a function

  cause Attempting to use the `pageview` method after upgrading to `react-ga4` v2.0.0 or later, where this method was removed.
  fix Replace `ReactGA.pageview('/some-path');` with `ReactGA.send({ hitType: 'pageview', page: '/some-path' });`.

• Google Analytics event 'your action' has no 'category' and 'action' attributes.

  cause Attempting to send a GA4 event with an incorrect object structure or missing required `category` and `action` properties.
  fix Ensure the object passed to `ReactGA.event()` includes both `category` and `action` properties, for example: `ReactGA.event({ category: 'UI', action: 'ButtonClick', label: 'Submit' });`.

Warnings

• breaking Version 3.0.1 and later are ESM-only modules. This means `require()` statements for importing `react-ga4` will fail. You must use ES module `import` syntax.
  Fix: Migrate your import statements from `const ReactGA = require('react-ga4');` to `import ReactGA from 'react-ga4';`
• breaking Version 2.0.0 removed the deprecated `pageview`, `outboundLink`, and `legacyDimensionMetric` methods. Explicit calls to `ReactGA.pageview()` will result in an error.
  Fix: Remove `ReactGA.pageview()` calls. To send custom page views, use `ReactGA.send({ hitType: 'pageview', page: '/my-path' });`. Note that page views are sent by default upon initialization and route changes if not explicitly disabled.
• gotcha The `ReactGA.event()` method signature for Google Analytics 4 is different from Universal Analytics. It expects an object with properties like `category`, `action`, `label`, `value`, etc., rather than positional arguments.
  Fix: Ensure you are passing an object to `ReactGA.event()`, e.g., `ReactGA.event({ category: 'Video', action: 'Play' });` instead of `ReactGA.event('Video', 'Play');`.
• gotcha By default, `react-ga4` sends a page view upon `initialize()`. If you are manually sending page views (e.g., within a React Router `useEffect`), you may end up with duplicate page views if not handled carefully.
  Fix: Consider disabling the default page view sending during initialization or ensure your manual page view logic accounts for this. If you are using a router, you might typically send page views on route changes rather than on initial load.

Install

• npm install react-ga4 npm
• yarn add react-ga4 yarn
• pnpm add react-ga4 pnpm

Imports

• ReactGA
  wrong:

  const ReactGA = require('react-ga4');

  correct:

  import ReactGA from 'react-ga4';

  Since v3.0.1, react-ga4 is an ESM-only module. CommonJS `require()` is no longer supported.
• initialize

  import ReactGA from 'react-ga4';
  ReactGA.initialize('G-MEASUREMENT_ID');

  The `initialize` method is the primary entry point for configuring GA4 with your Measurement ID. It can be called with a single ID or an array of objects for multiple trackers.
• send (pageview)
  wrong:

  ReactGA.pageview('/my-custom-path');

  correct:

  import ReactGA from 'react-ga4';
  ReactGA.send({ hitType: 'pageview', page: '/my-custom-path', title: 'Custom Page Title' });

  The `pageview` method was removed in v2.0.0. Use `ReactGA.send({ hitType: 'pageview', ... })` for custom page views. Default page views are sent automatically upon initialization.
• event
  wrong:

  ReactGA.event('Video', 'play', 'My Video', 100);

  correct:

  import ReactGA from 'react-ga4';
  ReactGA.event({ category: 'Video', action: 'play', label: 'My Video', value: 100 });

  For GA4, the `event` method expects an object with `category`, `action`, and optionally `label`, `value`, etc. The old positional arguments are not supported for GA4.

Quickstart

This quickstart initializes React GA4, demonstrates how to send a custom page view, and tracks a custom event when a button is clicked. It includes environment variable usage and a simulated route change.

import React from 'react';
import ReactDOM from 'react-dom/client';
import ReactGA from 'react-ga4';

// Replace 'G-YOUR_MEASUREMENT_ID' with your actual GA4 Measurement ID
const GA_MEASUREMENT_ID = process.env.REACT_APP_GA_MEASUREMENT_ID ?? 'G-YOUR_MEASUREMENT_ID';

if (GA_MEASUREMENT_ID) {
  ReactGA.initialize(GA_MEASUREMENT_ID, {
    testMode: process.env.NODE_ENV === 'development' // Optional: enable test mode in development
  });
  console.log('Google Analytics 4 initialized with ID:', GA_MEASUREMENT_ID);
} else {
  console.warn('Google Analytics 4 Measurement ID not found. GA will not be initialized.');
}

function App() {
  React.useEffect(() => {
    // Send an initial pageview when the component mounts
    // Note: ReactGA sends a default pageview on initialize, but this shows manual control.
    ReactGA.send({ hitType: 'pageview', page: window.location.pathname + window.location.search, title: document.title });

    const handleButtonClick = () => {
      ReactGA.event({
        category: 'User Interaction',
        action: 'Click',
        label: 'Submit Button',
        value: 1
      });
      console.log('GA4 event sent: Submit Button Click');
    };

    // Simulate a route change after 2 seconds
    const timeoutId = setTimeout(() => {
      const newPath = '/dashboard';
      ReactGA.send({ hitType: 'pageview', page: newPath, title: 'Dashboard Page' });
      console.log('GA4 pageview sent for:', newPath);
    }, 2000);

    return () => clearTimeout(timeoutId);

  }, []);

  return (
    <div>
      <h1>Welcome to the React GA4 Example!</h1>
      <p>Check your browser's network tab or GA4 debug view for tracking events.</p>
      <button onClick={handleButtonClick}>Send Custom Event</button>
    </div>
  );
}

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