How do I start tracking data with Matomo on websites that use React?

Matomo Tag Manager (MTM) supports React applications, including single-page applications (SPAs) that use client-side routing.

The same MTM configuration principles also apply to other SPA frameworks such as Nuxt, Vue, Angular, and Next.js. However, the application-side implementation may differ depending on how routing and page metadata are managed.

This guide explains how to configure page view tracking in a React application using Matomo Tag Manager.

Before you start

When you create a new website in Matomo, a Tag Manager container is automatically created with a preconfigured Matomo Analytics tag, pageview trigger, and configuration variable that you can use to get started quickly.

Ensure your implementation complies with your organisation’s privacy and consent requirements when enabling tracking in a React SPA.

Add a History trigger

The History Change trigger is the standard Matomo Tag Manager method for tracking SPA route changes. It automatically detects changes made through the browser history API, such as pushState and replaceState, which are commonly used by React Router and other SPA frameworks.

This is the simplest MTM setup with minimal custom code and works best when the tracked page title matches the browser title after each route change and the page title updates before the pageview tag fires.

1. In the Tag Manager container, navigate to Triggers and click Create new Trigger.
2. Under User Engagement, select the History Change trigger.
3. Provide a unique name and optional description.
4. Click Create New Trigger.
5. Go to Tags and edit the Matomo Analytics tag. If one does not exist in your container, create a new one.
6. The tag must reference your Matomo Configuration Variable with the Tracking type set to Pageview.
7. In the Custom Title field, choose the preconfigured variable {{PageTitle}}.
8. To use {{PageTitle}}, your React application must update document.title during route changes. This is usually handled inside a useEffect hook within the routed page component. See how to capture the correct page title in a React SPA.
9. In the Custom URL field, use the preconfigured variable {{PageOrigin}} or {{PageHash}} if your React app has a hash # in the URL. Otherwise, set it as {{PageUrl}}.
   
10. Under the option Execute this tag when any of these triggers are triggered, select the History Change trigger.
11. You can optionally include a Pageview trigger.
12. Test the setup and publish a new version of the updated container.

Add the tracking code in React

Ensure the Tag Manager container code is added to your App.js (or other relevant files). The example below shows how to add the tracking code into a Hello World app in React.js.

import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    var _mtm = window._mtm = window._mtm || [];

    _mtm.push({
      'mtm.startTime': new Date().getTime(),
      event: 'mtm.Start',
    });

    var d = document;
    var g = d.createElement('script');
    var s = d.getElementsByTagName('script')[0];

    g.async = true;
    g.src = '{YOUR_MATOMO_TAG_MANAGER_CONTAINER_URL}'; //Replace with your container code

    s.parentNode.insertBefore(g, s);
  }, []);

  return (
    <div>
      <h1>Hello World</h1>
    </div>
  );
}

Note: Replace “{YOUR_MATOMO_TAG_MANAGER_CONTAINER_URL}” with the container code you want to use.

Test the setup

1. Open your React app in a browser.
2. Confirm that each route updates the browser tab title. For example, Home should show the Home title, Contact show the Contact title.
   
3. In Matomo Tag Manager, open Preview/Debug mode.
4. Navigate between routes in your React app.
5. For each route change, check that the History Change trigger fires.
6. Confirm the Custom Title value matches the current browser tab title.
7. In Matomo, open the Real-time report or Visits Log and confirm each pageview shows the correct URL and page title.
8. If Matomo tracks the previous page title, the History Change trigger may be firing before React updates document.title. Read How to capture the correct page title in a React SPA.
9. Once you’ve confirmed that the trigger and tag are working as expected, publish the changes so that they’re deployed to your website.

You have now successfully installed the Matomo Analytics tracking code via the Matomo Tag Manager. To explore advanced setups, refer to the developer guide.