Skip to main content

Welcome to react-matomo-kit 🚀

Welcome to react-matomo-kit — a modern, type-safe, and developer-friendly integration for using Matomo Analytics in your React apps.

With this library, you can:

  • Track page views automatically (SPA-friendly)
  • Track custom events with type-safety
  • Track user identity and properties
  • Queue events if Matomo is not yet ready or if offline
  • Extend tracking easily with your own schema

Whether you're building a React app, a Next.js site, or an internal tool — react-matomo-kit helps you track meaningful analytics with minimal effort and without vendor lock-in.

Why this library?​

Matomo is a powerful open-source analytics platform. But its basic JavaScript API can feel low-level:

_paq.push(["trackEvent", "Category", "Action", "Name", 123]);

In modern React apps, this doesn't fit well with:

  • Type safety
  • Component architecture
  • Managing user state (who is the user? which dimensions are set?)
  • Offline-first apps (e.g. mobile web)

react-matomo-kit wraps the core Matomo API in a set of modern, ergonomic React patterns:

  • React Context for setup and access
  • useTrack() hook for type-safe events
  • MatomoAutoPageView for automatic page view tracking
  • Offline queueing out of the box

Key Concepts (Matomo 101)​

Page View​

A "Page View" is recorded when the user loads or navigates to a page.

In a Single Page App (SPA), you want this to happen on route change — not just on full reload. That is exactly what MatomoAutoPageView does.

Event Tracking​

An "Event" is a custom action you define — button click, form submission, etc.

Each event has:

  • Category (string)
  • Action (string)
  • Name (string, optional)
  • Value (number, optional)

User Identity​

Matomo supports identifying users with:

_paq.push(["setUserId", userId]);

And clearing it with:

_paq.push(["resetUserId"]);

This library exposes this in a simple API:

setUserId("user-123");
resetUserId();

Custom Dimensions​

Matomo lets you define Custom Dimensions — extra fields attached to every event or page view.

Example:

_paq.push(["setCustomDimension", 1, "Premium User"]);

In this library:

setCustomDimension(1, "Premium User");

Or in bulk:

setUserProperties({
  1: "Premium User",
  2: "Mobile",
});

Queueing​

If the Matomo JS has not loaded yet — or if the user is offline — this library will queue tracking events and send them later.

You don't need to do anything extra — it's automatic.

Example: Basic usage​

import {
  MatomoProvider,
  MatomoAutoPageView,
  createUseTrack,
  defineEventSchema,
} from "react-matomo-kit";

const eventSchema = defineEventSchema({
  user: {
    select: { category: "User", action: "Select" },
  },
  cat: {
    click: { category: "Cat", action: "Click" },
    submit: { category: "Cat", action: "Submit" },
  },
});

const useTrack = createUseTrack(eventSchema);

const matomoConfig = {
  siteId: "1",
  trackerUrl: "https://your.matomo.server/",
  srcUrl: "https://your.matomo.server/matomo.js",
};

export const App = () => (
  <BrowserRouter>
    <MatomoProvider config={matomoConfig} debug>
      <MatomoAutoPageView />
      <MyApp />
    </MatomoProvider>
  </BrowserRouter>
);

And in your components:

const { track } = useTrack();

track("cat.click", {
  name: "Clicked Cat Button",
  value: 1,
});

Summary​

This library aims to give you:

✅ A simple API that fits React apps
✅ Type safety for your tracking
✅ Automatic page view tracking
✅ Offline queueing
✅ Easy user + dimension tracking

Ready? Quick Start → 🚀