Scripts

Matomo Analytics

Copy for LLMs

Matomo Analytics 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.

Matomo Analytics

View source

Nuxt Config Setup

Add this to your nuxt.config.ts to load Matomo Analytics globally. Alternatively you can use the useScriptMatomoAnalytics composable for more control. 

export default defineNuxtConfig({
  scripts: {
    registry: {
      matomoAnalytics: {
        cloudId: 'my-site',
        trigger: 'onNuxtReady',
      }
    }
  }
})

This config automatically enables first-party mode (proxy). See below to customise.

useScriptMatomoAnalytics()

The useScriptMatomoAnalytics composable lets you have fine-grain control over when and how Matomo Analytics is loaded on your site. 

const { proxy } = useScriptMatomoAnalytics()

proxy._paq.push(['trackEvent', 'category', 'action'])

Please follow the Registry Scripts guide to learn more about advanced usage.

First-Party Mode: Privacy Focused Proxy

No extra config needed. Runtime requests are reverse-proxied through your server instead of going directly to Matomo Analytics. User IPs are anonymised and requests work with ad blockers. Learn more.

Mode
Bundle Proxy Partytown
Privacy
User IP addresses are anonymised. Other request data passes through.
export default defineNuxtConfig({
  scripts: {
    // ✅ First-party mode: proxied
    registry: {
      matomoAnalytics: {
        cloudId: 'my-site',
        trigger: 'onNuxtReady',
      },
    },
  },
})

Example

Using Matomo Analytics in a component with the proxy to send events . 

<script setup lang="ts">
const { proxy } = useScriptMatomoAnalytics()

// noop in development, ssr
// just works in production, client
function handleAction() {
  proxy._paq.push(['trackEvent', 'category', 'action'])
}
</script>

<template>
  <div>
    <button @click="handleAction">
      Send Event
    </button>
  </div>
</template>

By default, Nuxt uses a siteId of 1 and automatically enables page tracking via the watch option.

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 for all available options.

Custom Page Tracking

By default, Nuxt tracks all pages automatically; provide watch: false to disable automatic tracking.

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.

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.

useScriptMatomoAnalytics({
  trackerUrl: 'https://c.staging.cookie3.co/lake',
  scriptInput: {
    src: 'https://cdn.cookie3.co/scripts/latest/cookie3.analytics.min.js',
  },
})
matomoUrlstring

The URL of your self-hosted Matomo instance. Either `matomoUrl` or `cloudId` is required.

siteIdstring | number = '1'

Your Matomo site ID.

cloudIdstring

Your Matomo Cloud ID (the subdomain portion of your `*.matomo.cloud` URL). Either `matomoUrl` or `cloudId` is required.

trackerUrlstring

A custom tracker URL. Overrides the default tracker endpoint derived from `matomoUrl` or `cloudId`.

trackPageViewboolean

Whether to track the initial page view on load.

enableLinkTrackingboolean

Enable download and outlink tracking.

disableCookiesboolean

Disable all tracking cookies for cookieless analytics.

watchboolean = true

Automatically track page views on route change.

Edit this page
Markdown For LLMs

Lemon Squeezy

Use Lemon Squeezy in your Nuxt app.

Meta Pixel

Use Meta Pixel in your Nuxt app.