Matomo React is a comprehensive TypeScript library that seamlessly integrates Matomo analytics into your React applications. It provides a simple, yet powerful API for tracking user interactions, page views, events, and more, while maintaining full type safety.
Get started quickly with Matomo React by following this simple example:
import { MatomoProvider, useMatomo } from "@adam20054/react-matomo";
// Basic configuration
const config = {
trackerBaseUrl: "https://analytics.example.com",
siteId: 1
};
// App component with provider
function App() {
return (
<MatomoProvider config={config}>
<YourApp />
</MatomoProvider>
);
}
// Component using tracking
function HomePage() {
const { tracker } = useMatomo();
// Track page view when component mounts
React.useEffect(() => {
tracker.trackPageView();
}, [tracker]);
return <h1>Welcome to my site</h1>;
}Install the module from NPM registry:
npm:
npm i --save @adam20054/react-matomoyarn:
yarn add @adam20054/react-matomo- Set up the provider in your app's root component:
import { MatomoProvider } from "@adam20054/react-matomo";
const config = {
trackerBaseUrl: "https://analytics.example.com",
siteId: 1
};
function App() {
return (
<MatomoProvider config={config}>
<YourApp />
</MatomoProvider>
);
}- Use the tracker in your components:
import { useMatomo } from "@adam20054/react-matomo";
function YourComponent() {
const { tracker } = useMatomo();
// Track page view
React.useEffect(() => {
tracker.trackPageView();
}, [tracker]);
// Track an event
const handleButtonClick = () => {
tracker.trackEvent({
category: "User Interaction",
action: "Button Click",
name: "Get Started"
});
};
return (
<div>
<h1>Your Component</h1>
<button onClick={handleButtonClick}>Get Started</button>
</div>
);
}- Use the optimized event tracking hook for better performance:
import { useMatomoEvent } from "@adam20054/react-matomo";
function YourComponent() {
const { trackPageView, trackEvent } = useMatomoEvent();
// Track page view
React.useEffect(() => {
trackPageView();
}, [trackPageView]);
// Track an event (memoized function)
const handleButtonClick = () => {
trackEvent({
category: "User Interaction",
action: "Button Click",
name: "Get Started"
});
};
return (
<div>
<h1>Your Component</h1>
<button onClick={handleButtonClick}>Get Started</button>
</div>
);
}For a comprehensive guide on Matomo JavaScript tracking, see the Matomo JavaScript Tracking Guide.
| Option | Type | Required? | Description | Default |
|---|---|---|---|---|
siteId |
String/Number | âś… | The site identifier from your Matomo dashboard | - |
trackerBaseUrl |
String | âś… | Base URL of your Matomo installation. Can be: 1) Domain only (e.g., "https://analytics.example.com"), or 2) Path without file extension (e.g., "https://example.com/api/"). Matomo will assume you're using matamo.js/php as the filename unless matomo(Js/Php)FileName is specified in your config | - |
userId |
String | - | User identifier for cross-device tracking | - |
disableTracking |
Boolean | - | When true, disables all tracking | false |
deferTracking |
Boolean | - | Defers tracking until after critical content loads | false |
debug |
Boolean | - | Enables debug mode with console logging | false |
enableJSErrorTracking |
Boolean | - | Tracks JavaScript errors as events | false |
urlTransformer |
Function | - | Transforms URLs before tracking | - |
heartBeat |
Object | - | Configuration for heartbeat feature | { active: true, seconds: 15 } |
disableLinkTracking |
Boolean | - | Disables automatic link tracking | false |
matomoJsFileName |
String | - | Custom filename for Matomo JS (required if you need to use a custom filename) | "matomo.js" |
matomoPhpFileName |
String | - | Custom filename for Matomo PHP (required if you need to use a custom filename) | "matomo.php" |
requestMethod |
RequestMethod | - | HTTP method for tracking requests | RequestMethod.GET |
configurations |
Object | - | Additional Matomo configurations. For options not specifically built into the config options but still supported by Matomo. See Matomo JavaScript Tracking Guide for available options. | - |
The trackerBaseUrl option can be used in two different ways:
Click to see a URL configuration example
// 1. Domain only - standard matomo.js/php files at the root
const config1 = {
trackerBaseUrl: "https://analytics.example.com",
siteId: 1
};
// 2. Path without file extension - standard matomo.js/php files at that path
const config2 = {
trackerBaseUrl: "https://example.com/api/",
siteId: 1
};If you need to use custom filenames instead of the default "matomo.js" and "matomo.php", you must specify them explicitly:
Click to see a custom filename configuration example
const config = {
trackerBaseUrl: "https://analytics.example.com",
siteId: 1,
matomoJsFileName: "custom.js",
matomoPhpFileName: "custom.php"
};The urlTransformer option allows you to modify URLs before they are sent to Matomo:
Click to see a URL transformer example
const urlTransformer = (url: string) => {
// Remove UUIDs from the URL
const UUIDV4_REGEX = /[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}/g;
return url.replaceAll(UUIDV4_REGEX, "**MASKED**");
};
const config = {
trackerBaseUrl: "https://analytics.example.com",
siteId: 1,
urlTransformer
};This section covers the core tracking functionality provided by the library. These methods allow you to track various user interactions and behaviors in your React application. Click on each example to see the code.
Click to see page view tracking examples
// Basic page view tracking
tracker.trackPageView();
// With custom parameters
tracker.trackPageView({
documentTitle: "Custom Page Title",
href: "https://example.com/custom-path",
customDimensions: [
{ id: 1, value: "Premium" }
]
});Click to see event tracking examples
tracker.trackEvent({
category: "User Interaction",
action: "Button Click",
name: "Sign Up Button",
value: 1
});Click to see site search tracking examples
tracker.trackSiteSearch({
keyword: "react analytics",
category: "Documentation",
count: 5
});Custom dimensions can be included with any tracking call:
Click to see custom dimension examples
tracker.trackPageView({
customDimensions: [
{ id: 1, value: "Premium" },
{ id: 2, value: "Europe" }
]
});This section covers advanced Matomo tracking capabilities that can be implemented with this library. Each feature includes example code that can be expanded by clicking on it.
You can use any Matomo tracking feature through the addCustomInstruction method:
Click to see custom instruction examples
// Track a goal conversion
tracker.addCustomInstruction('trackGoal', 1, 50.0);
// Enable cross-domain linking
tracker.addCustomInstruction('enableCrossDomainLinking');
// Set a custom variable
tracker.addCustomInstruction('setCustomVariable', 1, 'Category', 'Sports', 'page');Click to see ecommerce tracking examples
// Add an item to the cart
tracker.addCustomInstruction('addEcommerceItem',
'SKU123', // Product SKU
'Product Name', // Product name
'Product Category', // Product category
99.99, // Product price
2 // Quantity
);
// Track a cart update
tracker.addCustomInstruction('trackEcommerceCartUpdate', 199.98);
// Track an order
tracker.addCustomInstruction('trackEcommerceOrder',
'ORDER123', // Order ID
199.98, // Grand total
180.00, // Subtotal
19.98, // Tax
0, // Shipping
0 // Discount
);Click to see goal tracking examples
// Track a goal conversion
tracker.addCustomInstruction('trackGoal', 1);
// Track a goal conversion with revenue
tracker.addCustomInstruction('trackGoal', 1, 50.0);Click to see content tracking examples
// Track all content impressions on the page
tracker.addCustomInstruction('trackAllContentImpressions');
// Track only visible content impressions
tracker.addCustomInstruction('trackVisibleContentImpressions', true, 750);
// Track a content impression manually
tracker.addCustomInstruction('trackContentImpression',
'Content Name',
'Content Piece',
'https://example.com'
);
// Track a content interaction manually
tracker.addCustomInstruction('trackContentInteraction',
'click',
'Content Name',
'Content Piece',
'https://example.com'
);Click to see consent management examples
// Require consent before tracking
tracker.addCustomInstruction('requireConsent');
// Set consent for the current user
tracker.addCustomInstruction('setConsentGiven');
// Remember consent for the current user
tracker.addCustomInstruction('rememberConsentGiven', 30); // 30 days
// Forget consent for the current user
tracker.addCustomInstruction('forgetConsentGiven');Click to see download and outlink tracking examples
// Set custom file extensions to be recognized as downloads
tracker.addCustomInstruction('setDownloadExtensions', 'zip|rar|pdf');
// Add additional file extensions to be recognized as downloads
tracker.addCustomInstruction('addDownloadExtensions', 'docx|xlsx');
// Manually track a download
tracker.addCustomInstruction('trackLink', 'https://example.com/file.pdf', 'download');
// Manually track an outlink
tracker.addCustomInstruction('trackLink', 'https://external-site.com', 'link');Click to see cross-domain tracking examples
// Enable cross-domain linking
tracker.addCustomInstruction('enableCrossDomainLinking');
// Set the domains to be treated as local
tracker.addCustomInstruction('setDomains', ['example.com', '*.example.org']);Click to see custom variable examples
// Set a custom variable for the current visit
tracker.addCustomInstruction('setCustomVariable', 1, 'Gender', 'Male', 'visit');
// Set a custom variable for the current page view
tracker.addCustomInstruction('setCustomVariable', 2, 'Category', 'Sports', 'page');Click to see multiple tracker configuration examples
// Add a second tracker to track data to another Matomo instance
tracker.addCustomInstruction('addTracker', 'https://another-matomo.com/matomo.php', 2);This section provides techniques to optimize the performance impact of Matomo tracking in your React application. These optimizations help ensure that analytics tracking doesn't negatively affect your application's user experience.
You can defer tracking until after critical page content has loaded:
Click to see deferred tracking configuration example
const config = {
trackerBaseUrl: "https://analytics.example.com",
siteId: 1,
deferTracking: true
};This improves initial page load performance by loading the Matomo script with lower priority.
Use the useMatomoEvent hook for optimized event tracking with memoized functions:
Click to see optimized event tracking examples
import { useMatomoEvent } from "@adam20054/react-matomo";
function YourComponent() {
const { trackEvent } = useMatomoEvent();
// This function won't cause unnecessary re-renders
const handleClick = () => {
trackEvent({
category: "User Interaction",
action: "Button Click"
});
};
return <button onClick={handleClick}>Click Me</button>;
}When implementing Matomo tracking, it's helpful to verify that events are being tracked correctly. The debug mode provides detailed logging to help you troubleshoot any issues:
Enable debug mode to log tracking information to the console:
Click to see debugging configuration example
const config = {
trackerBaseUrl: "https://analytics.example.com",
siteId: 1,
debug: true
};This will log:
- All tracking commands sent to Matomo
- Warnings about deprecated or misconfigured options
- Information about tracking being disabled or skipped
Contributions are welcome! If you'd like to contribute to this project, please follow these steps:
- Fork the repository
- Create a new branch for your feature or bugfix
- Make your changes
- Add or update tests as necessary
- Run the tests to make sure everything passes
- Submit a pull request
Please make sure your code follows the existing style and includes appropriate tests.
This project is licensed under the MIT Licence.
This project builds upon the foundations of React Matomo Tracker and Matomo-Tracker, enhancing them with advanced customization options, improved TypeScript support, and modern React patterns.
Originally created to enable custom Matomo tracker URLs (beyond the standard Matomo.js/php), the library has evolved into a complete solution for React analytics with an emphasis on developer experience and flexibility.