Skip to main content

​
Overview

The Plausible Analytics tracker is a lightweight JavaScript snippet that enables privacy-focused web analytics on your website. It automatically captures pageviews and can be configured to track custom events, file downloads, outbound links, and more.

​
Installation Methods

There are two primary ways to integrate Plausible Analytics into your website:
Add the Plausible script to your website’s <head> section:
<script defer data-domain="yourdomain.com" src="https://plausible.io/js/script.js"></script>
Replace yourdomain.com with your actual domain name as configured in your Plausible account.
The defer attribute ensures the script loads asynchronously without blocking page rendering.

​
Configuration Options

The tracker accepts various configuration options to customize its behavior:

​
Script Attributes

When using the script tag method, configure behavior through data attributes:
AttributeDescriptionExample
data-domainRequired - Your site’s domaindata-domain="example.com"
data-apiCustom API endpoint for proxyingdata-api="https://analytics.example.com/api/event"
data-excludeExclude specific pages from trackingdata-exclude="/admin/**"
data-includeOnly track specific pagesdata-include="/blog/**"

​
NPM Configuration

When using the NPM package, pass configuration options to the init function: 
import { init } from '@plausible-analytics/tracker'

init({
  domain: 'my-app.com',
  endpoint: 'https://plausible.io/api/event',
  autoCapturePageviews: true,
  hashBasedRouting: false,
  outboundLinks: false,
  fileDownloads: false,
  formSubmissions: false,
  captureOnLocalhost: false,
  logging: true,
  bindToWindow: true
})

​
Configuration Reference

​
domain
string
required
Your site’s domain, as declared in your Plausible account settings.
​
endpoint
string
default:"https://plausible.io/api/event"
The URL of the Plausible API endpoint. See the proxy guide for custom endpoints.
​
autoCapturePageviews
boolean
default:"true"
Whether to automatically capture pageviews. Set to false for manual pageview tracking.
​
hashBasedRouting
boolean
default:"false"
Enable for single-page applications using hash-based routing (e.g., #/page). Read more in the hash-based routing docs.
​
outboundLinks
boolean
default:"false"
Automatically track clicks on outbound links.
​
fileDownloads
boolean | object
default:"false"
Track file downloads. Can be true or an object with custom file extensions:
fileDownloads: { fileExtensions: ['pdf', 'zip', 'csv'] }
​
formSubmissions
boolean
default:"false"
Automatically track form submissions.
​
captureOnLocalhost
boolean
default:"false"
Enable event capture on localhost for testing.
​
logging
boolean
default:"true"
Log warnings when events are ignored.
​
bindToWindow
boolean
default:"true"
Binds track function to window.plausible for verification and debugging.

​
Advanced Usage

​
Manual Initialization

For advanced control, you can manually initialize the tracker with custom settings: 
<script>
window.plausible = window.plausible || function() {
  (plausible.q = plausible.q || []).push(arguments)
}
plausible.init = plausible.init || function(overrides) {
  plausible.o = overrides || {}
}

plausible.init({
  // Custom configuration
})
</script>
<script defer src="https://plausible.io/js/script.js"></script>

​
Proxying the Tracker

To avoid ad-blockers, proxy the Plausible script through your own domain: 
<script defer data-domain="yourdomain.com" 
  data-api="https://analytics.yourdomain.com/api/event" 
  src="https://analytics.yourdomain.com/js/script.js"></script>
See the proxy documentation for setup instructions.

​
Excluding Pages

Exclude specific pages from tracking using wildcard patterns: 
<script defer data-domain="yourdomain.com" 
  data-exclude="/admin/**,/dashboard/**" 
  src="https://plausible.io/js/script.js"></script>
Supported wildcard patterns:
  • * - matches any characters except forward slashes
  • ** - matches any characters including forward slashes

​
Verification

After installing the tracker, verify it’s working correctly:
1

Check Browser Console

Open your browser’s developer console and look for any Plausible-related warnings or errors.
2

Verify window.plausible

Type window.plausible in the console. If the tracker is loaded, you should see a function.
3

Check Network Tab

Navigate your site and check the Network tab for requests to /api/event with status code 202.
4

View Real-time Dashboard

Visit your Plausible dashboard and check the real-time visitor count.

​
Opt-out

Users can opt out of tracking by setting a localStorage flag: 
localStorage.setItem('plausible_ignore', 'true')
The tracker will not send events if localStorage.plausible_ignore is set to "true". More information: Excluding with localStorage

​
Next Steps

Custom Events

Track custom goals and user interactions

Custom Properties

Add metadata to your events

Events API

Server-side event tracking

Framework Guides

Integration guides for popular frameworks

Build docs developers (and LLMs) love

Get started for freeTalk to us