ngx-matomo-client

November 21, 2025 · View on GitHub

Configuration reference

Below are all configuration properties that you can use when you initialize Matomo (either using provideMatomo(options, ...additionalFeatures) or the classic NgModule):

import {
  provideMatomo,
  withRouter,
  withScriptFactory,
  withRouterInterceptors,
} from 'ngx-matomo-client';

@NgModule({
  providers: [
    provideMatomo(
      // Main options here:
      {
        siteId: 42,
        trackerUrl: 'http://...',
      },

      // Optionally add one or more features:
      withRouter({
        // Router options here
      }),
      withScriptFactory(),
      withRouterInterceptors(),
    ),
  ],
})
export class AppModule {}

See equivalent configuration with @NgModule

import { MatomoModule, MatomoRouterModule, MatomoRouteDataInterceptor } from 'ngx-matomo-client';

@NgModule({
  imports: [
    MatomoModule.forRoot({
      // Main options here
      siteId: 42,
      trackerUrl: 'http://...',
    }),
    MatomoRouterModule.forRoot({
      // Router options here
    }),
  ],
})
export class AppModule {}

Options

Main configuration options (for provideMatomo() or MatomoModule.forRoot()) are:

Option	Type	Default value	Description	Available in `'manual'` mode
mode	`MatomoInitializationBehavior`	`'auto'`	Set whether tracking code should be automatically embedded or not. If set to `'manual'`, some other option cannot be used.	-
siteId	`number` or `string`	required, unless `trackers` is set	Your Matomo site id (may be found in your Matomo server's settings).	no
trackerUrl	`string`	required, unless `trackers` is set	Your Matomo server url.	no
trackerUrlSuffix	`string`	`matomo.php`	Suffix to append to `trackerUrl`.	no
trackers	array of `{siteId: string, trackerUrl: string, trackerUrlSuffix?: string}`	none, required unless `siteId` and `trackerUrl` are set	A list of multiple Matomo servers. Note that tracking code will be downloaded from the FIRST tracker in the list (unless `scriptUrl` option is set). Mutually exclusive with the three previous options.	no
scriptUrl	`string`	tracker url suffixed with `matomo.js`	Url of Matomo tracker's script.	no
disabled	`boolean`	`false`	If set to `true` then all tracking operations become no-op. Note that in this case, all getter methods will return rejected Promises.	yes
trackAppInitialLoad	`boolean`	`false` if router is enabled, `true` otherwise	If set to `true`, will call trackPageView on application init. This should probably never be used on a routed single-page application.	yes
enableLinkTracking	`boolean` or `'enable-pseudo'`	`true`	If set to `true` (the default), enable link tracking, excluding middle-clicks and contextmenu events. If set to `enable-pseudo`, enable link tracking, including middle-clicks and contextmenu events. If set to `false`, disable link tracking.	yes
enableJSErrorTracking	`boolean`	`false`	If set to `true`, enable JS errors tracking.	yes
acceptDoNotTrack	`boolean`	`false`	Set whether to not track users who opt out of tracking using Do Not Track setting	yes
requireConsent	`MatomoConsentRequirement`	`'none'`	Configure user consent requirement.	yes
runOutsideAngularZone	`boolean`	`true`	If set to `true`, will run matomo calls outside of angular's NgZone. This may help if the call causes the app to freeze. This has no effect in zoneless applications.	yes

Router configuration options (for withRouter() or MatomoRouterModule.forRoot()) are:

Option	Type	Default value	Description
prependBaseHref	`boolean`	`true`	Set whether the application's base href should be prepended to current url when tracking page views. Set it to `false` to disable this behavior.
trackPageTitle	`boolean`	`true`	Set whether to detect page title when tracking views. By default, page title is automatically detected from DOM document title. Note that if set to `false`, Matomo is likely to still use the initial document title for all tracked page views.
delay	`number` Set to `-1` to run synchronously	`0` (no delay but still asynchronous)	Set a delay after navigation event before page view is tracked. If your document title is updated asynchronously after Router events, you may have to set a delay to correctly detect document title. If set to `0`, tacking is still asynchronous. Set it to `-1` to execute tracking synchronously. See also previous sections for more advanced page title customization.
exclude	`string`, `RegExp`, `string[]` or `RegExp[]`	`[]`	Set some url patterns to exclude from page views tracking.

Additional features

Available features for provideMatomo() are:

withRouter

Enable automatic page view tracking. This requires @angular/router.

See options for router configuration above.

withRouteData

Add automatic Matomo data retrieval from Angular routes configuration. This requires withRouter() feature. See Using route data in README for details.

withRouterInterceptors

Add interceptors to hook into the automatic page view tracking. This requires withRouter() feature. See Using custom interceptor in README for details.

withScriptFactory

Allow to customize Matomo's script element creation. See How can I customize the inserted script tag? in FAQ.

withFormAnalytics

Allow to use the Form Analytics plugin of Matomo. See Plugins > Form Analytics in FAQ.