Plausible Tracker

Because the tracker is bundled with your application code, standard ad-blockers may not prevent your own visits from being tracked. To opt out, set the following key in your browser's localStorage:

localStorage.plausible_ignore = "true"

When this is set, the tracker will not send any events.

Install the library using npm or yarn to begin interacting with Plausible Analytics in your frontend application.

npm install plausible-tracker

yarn add plausible-tracker

For Single Page Applications (SPAs) using JS-based routing, enableAutoPageviews() automatically tracks page views by overriding history.pushState and listening to popstate and hashchange events.

Hash-based Routing

If your app uses URL hashes for navigation, initialize the tracker with hashMode: true before calling enableAutoPageviews().

Cleaning up

enableAutoPageviews() returns a cleanup function. Call this function to remove event listeners and restore the original history.pushState behavior.

import Plausible from 'plausible-tracker'

const { enableAutoPageviews } = Plausible({
  hashMode: true
})

// Starts tracking current and future page views
const cleanup = enableAutoPageviews()

// Later, to stop tracking and restore history behavior:
cleanup()

To start tracking, call the Plausible() function with a configuration object. This returns an object containing tracking methods like trackPageview, trackEvent, and enableAutoPageviews.

Initialization Options

import Plausible from 'plausible-tracker'

const plausible = Plausible({
  domain: 'my-app.com'
})

The enableAutoOutboundTracking() function adds a click event listener to all <a> tags and uses a MutationObserver to ensure dynamically added links are also tracked.

Cleaning up

enableAutoOutboundTracking() returns a cleanup function. Call it to remove the click listeners and disconnect the MutationObserver.

import Plausible from 'plausible-tracker'

const { enableAutoOutboundTracking } = Plausible()

// Start tracking all existing and future outbound links
const cleanup = enableAutoOutboundTracking()

// Later, to stop tracking:
cleanup()

Use trackEvent(name, eventOptions, overrideOptions) to track custom user actions or goals.

• name: The name of the goal or event (string).
• eventOptions: An object containing props (custom properties) and a callback function.
• overrideOptions: An object containing the same configuration options used during initialization (e.g., trackLocalhost, domain).

import Plausible from 'plausible-tracker'

const { trackEvent } = Plausible()

// Track a simple goal
trackEvent('signup')

// Track a goal with custom properties
trackEvent('download', { props: { method: 'HTTP' } })

// Track a goal with properties, a callback, and initialization overrides
trackEvent(
  'signup',
  {
    callback: () => console.log('done'),
    props: { variation: 'button A' }
  },
  { trackLocalhost: true }
)

The Plausible class is the main entrypoint for the tracker. You initialize it by importing the default export and providing a configuration object that satisfies the PlausibleOptions type. This instance is then used to track page views and custom events.

import Plausible from 'plausible-tracker';

const tracker = new Plausible({
  domain: 'yourdomain.com',
  apiHost: 'https://plausible.io'
});

Use trackEvent to track custom goals or user actions. You can pass a name for the event, optional event properties (via EventOptions), and optional event data (via PlausibleOptions).

Parameters:

• eventName: The name of the event (e.g., 'signup').
• options: (Optional) EventOptions for the request.
• eventData: (Optional) PlausibleOptions to override default metadata like url or domain.

import Plausible from 'plausible-tracker'

const { trackEvent } = Plausible()

// Tracks the 'signup' goal
trackEvent('signup')

// Tracks the 'Download' goal passing a 'method' property.
trackEvent('Download', { props: { method: 'HTTP' } })

Use trackPageview to manually record a page view. This is useful for single-page applications (SPAs) where you want to trigger a pageview event on specific route changes without using the automatic mode.

import Plausible from 'plausible-tracker'

const { trackPageview } = Plausible()

// Track a page view
trackPageview()