---
title: "Matomo Analytics · Nuxt Scripts"
meta:
  description: "Nuxt Scripts lets you load third-party scripts with better performance, privacy, security and DX. It includes many popular third-parties out of the box."
  "og:description": "Nuxt Scripts lets you load third-party scripts with better performance, privacy, security and DX. It includes many popular third-parties out of the box."
  "og:title": "Matomo Analytics · Nuxt Scripts"
---

```

Nuxt Scripts on GitHub

**

**Analytics**# **Matomo Analytics**[Copy for LLMs](https://scripts.nuxt.com/scripts/v0/analytics/matomo-analytics.md) [**~~Matomo Analytics~~**](https://matomo.org/) is a great analytics solution for Nuxt Apps. It provides detailed insights into how your website is performing, how users are interacting with your content, and how they are navigating through your site. The simplest way to load Matomo Analytics globally in your Nuxt App is to use Nuxt config. Alternatively you can directly use the **~~useScriptMatomoAnalytics~~** composable. ## Loading Globally The following config assumes you're using Matomo Cloud with the default `siteId` of `1`. Page views are **automatically tracked** on navigation by default. If you're self-hosting, you'll need to provide the `matomoUrl` instead. If you have other sites you want to track, you can add them using `siteId`.```
export default defineNuxtConfig({
  scripts: {
    registry: {
      matomoAnalytics: {
        cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
      }
    }
  }
})
``````
export default defineNuxtConfig({
  $production: {
    scripts: {
      registry: {
        matomoAnalytics: {
          cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
        }
      }
    }
  }
})
``````
export default defineNuxtConfig({
  scripts: {
    registry: {
      matomoAnalytics: true,
    }
  },
  // you need to provide a runtime config to access the environment variables
  runtimeConfig: {
    public: {
      scripts: {
        matomoAnalytics: {
          // .env
          // NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_CLOUD_ID=<your-id>
          cloudId: '', // NUXT_PUBLIC_SCRIPTS_MATOMO_ANALYTICS_CLOUD_ID
        },
      },
    },
  },
})
```## useScriptMatomoAnalytics The `useScriptMatomoAnalytics` composable lets you have fine-grain control over when and how Matomo Analytics is loaded on your site.```
const matomoAnalytics = useScriptMatomoAnalytics({
  cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
})
``` By default, a `siteId` of `1` is used and page tracking is **automatically enabled** via the `watch` option.```
const matomoAnalytics = useScriptMatomoAnalytics({
  cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
  siteId: 2,
  // watch: true, // enabled by default - automatic page tracking!
})
``` If you'd like more control over the tracking, for example to set a custom dimension, you can send events using the `proxy` object.```
const { proxy } = useScriptMatomoAnalytics({
  cloudId: 'YOUR_CLOUD_ID', // e.g. nuxt.matomo.cloud
})

// set custom dimension
proxy._paq.push(['setCustomDimension', 1, 'value'])
// send page event
proxy._paq.push(['trackPageView'])
``` Please see the [**~~Config Schema~~**](#config-schema) for all available options. ## Custom Page Tracking By default, all pages are tracked automatically, to disable the automatic tracking you can provide `watch: false`.```
import { useScriptEventPage } from '#nuxt-scripts'

const { proxy } = useScriptMatomoAnalytics({
  cloudId: 'YOUR_CLOUD_ID',
  watch: false, // disable automatic tracking
})

// Custom page tracking with additional logic
useScriptEventPage((payload) => {
  // Set custom dimensions based on route
  if (payload.path.startsWith('/products')) {
    proxy._paq.push(['setCustomDimension', 1, 'Product Page'])
  }

  // Standard Matomo tracking calls (same as built-in watch behavior)
  proxy._paq.push(['setDocumentTitle', payload.title])
  proxy._paq.push(['setCustomUrl', payload.path])
  proxy._paq.push(['trackPageView'])

  // Track additional custom events
  proxy._paq.push(['trackEvent', 'Navigation', 'PageView', payload.path])
})
```### Using Matomo Self-Hosted For self-hosted Matomo, set `matomoUrl` to customize tracking, you may need to set the `trackerUrl` if you've customized this.```
const matomoAnalytics = useScriptMatomoAnalytics({
  // e.g. https://your-url.com/tracker.js & https://your-url.com//matomo.php both exists
  matomoUrl: 'https://your-url.com',
})
```### Using Matomo Whitelabel For Matomo Whitelabel, set `trackerUrl` and `scriptInput.src` to customize tracking.```
const matomoAnalytics = useScriptMatomoAnalytics({
  trackerUrl: 'https://c.staging.cookie3.co/lake',
  scriptInput: {
    src: 'https://cdn.cookie3.co/scripts/analytics/latest/cookie3.analytics.min.js',
  },
})
``` Please follow the [**~~Registry Scripts~~**](https://scripts.nuxt.com/docs/guides/registry-scripts) guide to learn more about advanced usage. ### MatomoAnalyticsApi```
interface MatomoAnalyticsApi {
  _paq: unknown[]
}
```### Config Schema You must provide the options when setting up the script for the first time.```
// matomoUrl and site are required
export const MatomoAnalyticsOptions = object({
  matomoUrl: optional(string()),
  siteId: optional(union([string(), number()])),
  cloudId: optional(string()),
  trackerUrl: optional(string()),
  trackPageView: optional(boolean()), // deprecated - use watch instead
  enableLinkTracking: optional(boolean()),
  disableCookies: optional(boolean()),
  watch: optional(boolean()), // default: true
})
```## Example Using Matomo Analytics only in production while using `_paq` to send a conversion event.```
<script setup lang="ts">
const { proxy } = useScriptMatomoAnalytics()

// noop in development, ssr
// just works in production, client
function sendConversion() {
  proxy._paq.push(['trackGoal', 1])
}
</script>

<template>
  <div>
    <button @click="sendConversion">
      Send Conversion
    </button>
  </div>
</template>
```[~~Edit this page~~](https://github.com/nuxt/scripts/edit/0.x/docs/content/scripts/v0/analytics/matomo-analytics.md) [~~Markdown For LLMs~~](https://scripts.nuxt.com/scripts/v0/analytics/matomo-analytics.md) [**Google Analytics** Use Google Analytics in your Nuxt app.](https://scripts.nuxt.com/scripts/v0/analytics/google-analytics) [**Plausible Analytics** Use Plausible Analytics in your Nuxt app.](https://scripts.nuxt.com/scripts/v0/analytics/plausible-analytics)**On this page **- [Loading Globally](#loading-globally) - [useScriptMatomoAnalytics](#usescriptmatomoanalytics) - [Custom Page Tracking](#custom-page-tracking) - [Example](#example)