Skip to main content

Quick Start

This guide will show you how to add react-matomo-kit to your React app in just a few minutes.

1. Install the package​

npm install react-matomo-kit
# or
yarn add react-matomo-kit

2. Define your event schema​

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

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

export const useTrack = createUseTrack(eventSchema);

3. Configure the Matomo Provider​

Wrap your app with MatomoProvider:

import { MatomoProvider, MatomoAutoPageView } from "react-matomo-kit";
import { BrowserRouter } from "react-router-dom";
import { matomoConfig } from "./matomo"; // your matomoConfig

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

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

4. Track events in your components​

import { useTrack } from "../matomo";

const MyComponent = () => {
  const { track } = useTrack();

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

  return <button onClick={handleClick}>Click Me!</button>;
};

5. (Optional) Set User Info​

import { useMatomo } from "react-matomo-kit";

const MyComponent = () => {
  const { setUserId, setUserProperties } = useMatomo();

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

  return <button onClick={login}>Login</button>;
};

✅ That’s it — your app is now tracking with Matomo! 🚀

Next → Core Concepts