Skip to main content

Core Concepts

react-matomo-kit is built to provide a React-friendly, type-safe abstraction over the Matomo Analytics API.

If you are new to Matomo — don’t worry. You don’t need to be an expert! The library provides simple hooks and components you can use right away.

Tracking in React​

Traditional Matomo tracking uses the global _paq array:

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

In React apps — especially SPAs — this approach is problematic:

  • You may not know when the Matomo script is ready
  • You want to avoid global mutable state
  • You want to queue events automatically if Matomo isn’t ready

react-matomo-kit solves this:

  • Provides React Context for setup
  • Handles offline/early queueing automatically
  • Gives you simple hooks like useTrack() and useMatomo()

Automatic Page View tracking​

In Matomo, a "Page View" is an event that tells the analytics system "the user navigated to a new page."

In SPAs, route changes do not trigger full page loads — so Matomo must be notified manually.

react-matomo-kit provides:

<MatomoAutoPageView />

which automatically tracks route changes.

Event tracking​

You can define your own event schema:

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

const useTrack = createUseTrack(eventSchema);

And then:

const { track } = useTrack();

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

User identity & properties​

You can easily track the current user:

const { setUserId, resetUserId, setUserProperties } = useMatomo();

setUserId("user-123");
setUserProperties({
  1: "Premium",
  2: "Mobile",
});

Offline queue​

If the Matomo script is not ready (e.g. loaded late), or if the user is offline:

  • Events will be queued automatically.
  • When the script is ready / connection returns — they will be sent.

You can configure queue size and see the current queue:

const { queueSize, lastFlushTimestamp } = useMatomo();

Summary​

  • Automatic Page Views
  • Type-safe custom events
  • User identity and custom dimensions
  • Offline queue
  • SPA-friendly, no global state