Skip to main content

​
Overview

Custom events allow you to track specific user interactions beyond pageviews, such as button clicks, form submissions, video plays, purchases, and more. Unlike pageviews, custom events require explicit tracking calls.

​
Tracking Methods

There are three ways to track custom events in Plausible:
  1. JavaScript API - Programmatically track events using the track() function
  2. Tagged Elements - Automatically track clicks on elements with CSS classes
  3. Auto-capture - Enable automatic tracking of file downloads, outbound links, and form submissions

​
JavaScript API

​
Basic Event Tracking

Use the track() function to send custom events: 
// Track a simple event
window.plausible('Signup');

// Track with custom properties
window.plausible('Signup', {
  props: {
    plan: 'premium',
    method: 'google'
  }
});

​
Event Options

The track() function accepts an options object with the following fields:
​
props
object
Custom properties to attach to the event. All keys and values must be strings.
track('Purchase', {
  props: {
    product: 'Pro Plan',
    tier: 'monthly'
  }
});
​
interactive
boolean
default:"true"
Whether the event is interactive. Non-interactive events don’t affect bounce rate calculations.
track('Video Autoplay', {
  interactive: false
});
​
revenue
object
Revenue information for ecommerce tracking.
track('Purchase', {
  revenue: {
    amount: 29.99,
    currency: 'USD'
  }
});
​
callback
function
Called when the tracking request completes or is ignored.
track('Signup', {
  callback: (result) => {
    if (result?.status) {
      console.log('Tracked successfully');
    } else if (result?.error) {
      console.error('Tracking error:', result.error);
    } else {
      console.log('Event was ignored');
    }
  }
});
​
url
string
Override the URL of the page where the event occurred. By default, uses location.href.
track('Modal Viewed', {
  url: 'https://example.com/modal/pricing'
});

​
Tagged Events

Tagged events allow you to track interactions without writing JavaScript. Simply add CSS classes to your HTML elements.

​
Basic Tagged Elements

Add the plausible-event-name class to track clicks: 
<button class="plausible-event-name=Signup">Sign Up</button>

<a href="/pricing" class="plausible-event-name=View+Pricing">View Pricing</a>
Use + or spaces to separate words in event names within class names.

​
Tagged Events with Properties

Add custom properties using additional classes: 
<button 
  class="plausible-event-name=Signup plausible-event-plan=premium plausible-event-method=email">
  Sign Up for Premium
</button>
This tracks a “Signup” event with properties: 
{
  plan: 'premium',
  method: 'email'
}

​
Alternative Syntax

You can use -- instead of = for better compatibility with some frameworks: 
<button class="plausible-event-name--Signup plausible-event-plan--premium">
  Sign Up
</button>
When tracking clicks on links, the URL is automatically added as a property: 
<a href="https://github.com/plausible" 
   class="plausible-event-name=External+Link plausible-event-target=GitHub">
  View on GitHub
</a>
This creates an event with: 
{
  target: 'GitHub',
  url: 'https://github.com/plausible'
}

​
Tagged Forms

Track form submissions by adding classes to the <form> element: 
<form class="plausible-event-name=Newsletter+Signup plausible-event-location=Footer">
  <input type="email" placeholder="Enter your email" />
  <button type="submit">Subscribe</button>
</form>

​
Auto-capture Features

Plausible can automatically track common interactions when enabled.

​
File Downloads

Automatically track clicks on file download links: 
import { init } from '@plausible-analytics/tracker'

init({
  domain: 'example.com',
  fileDownloads: true
});
Default tracked file types: 
[
  'pdf', 'xlsx', 'docx', 'txt', 'rtf', 'csv', 'exe', 'key',
  'pps', 'ppt', 'pptx', '7z', 'pkg', 'rar', 'gz', 'zip',
  'avi', 'mov', 'mp4', 'mpeg', 'wmv', 'midi', 'mp3', 'wav',
  'wma', 'dmg'
]

​
Custom File Types

import { init, DEFAULT_FILE_TYPES } from '@plausible-analytics/tracker'

init({
  domain: 'example.com',
  fileDownloads: {
    fileExtensions: ['pdf', 'zip', 'mp4']  // Only these types
  }
});

// Or extend defaults
init({
  domain: 'example.com',
  fileDownloads: {
    fileExtensions: [...DEFAULT_FILE_TYPES, 'sketch', 'fig']
  }
});
File downloads are tracked as “File Download” events with a url property: 
{
  name: 'File Download',
  props: {
    url: 'https://example.com/documents/report.pdf'
  }
}
Automatically track clicks on external links: 
import { init } from '@plausible-analytics/tracker'

init({
  domain: 'example.com',
  outboundLinks: true
});
Outbound link clicks are tracked as “Outbound Link: Click” events: 
{
  name: 'Outbound Link: Click',
  props: {
    url: 'https://external-site.com/page'
  }
}
An outbound link is any link where the host differs from the current page’s location.host.

​
Form Submissions

Automatically track form submissions: 
import { init } from '@plausible-analytics/tracker'

init({
  domain: 'example.com',
  formSubmissions: true
});
Form submissions are tracked as “Form: Submission” events when the form passes validation.
If a form has tagged event classes, it will not be tracked as a generic “Form: Submission”. Only the custom tagged event will fire.

​
Combined Features

Use a combined script to enable multiple features: 
<script defer data-domain="example.com" 
  src="https://plausible.io/js/script.outbound-links.file-downloads.js"></script>
Available script variants:
  • script.js - Base tracker
  • script.file-downloads.js - With file download tracking
  • script.outbound-links.js - With outbound link tracking
  • script.tagged-events.js - With tagged events support
  • Combinations like script.outbound-links.file-downloads.js

​
Revenue Tracking

Track revenue and ecommerce conversions: 
import { track } from '@plausible-analytics/tracker'

track('Purchase', {
  props: {
    product: 'Pro Plan',
    billing: 'monthly'
  },
  revenue: {
    amount: 29.99,
    currency: 'USD'
  }
});
​
revenue.amount
number | string
required
Revenue amount in the specified currency.
​
revenue.currency
string
required
ISO 4217 currency code (e.g., “USD”, “EUR”, “GBP”).
For more details, see ecommerce revenue tracking.

​
Event Naming Guidelines

1

Use Clear, Descriptive Names

Choose names that clearly describe the action:
  • ✅ “Signup”, “Download PDF”, “Add to Cart”
  • ❌ “Event1”, “Click”, “Action”
2

Be Consistent

Use a consistent naming convention across your site:
  • Capitalization: “Signup” or “signup”, not both
  • Spacing: “Add to Cart” or “Add_to_Cart”, not both
3

Keep It Simple

Avoid overly long or complex names. Use properties for additional context.
4

Configure Goals

Remember to add custom events as goals in your Plausible dashboard to see them in reports.

​
Common Patterns

​
Button Clicks

document.querySelector('#cta-button').addEventListener('click', () => {
  track('CTA Clicked', {
    props: {
      location: 'hero',
      variant: 'blue'
    }
  });
});

​
Video Engagement

videoPlayer.on('play', () => {
  track('Video Play', {
    props: { video: 'product-demo' }
  });
});

videoPlayer.on('complete', () => {
  track('Video Complete', {
    props: { video: 'product-demo' }
  });
});

​
Newsletter Signups

form.addEventListener('submit', (e) => {
  e.preventDefault();
  
  track('Newsletter Signup', {
    props: {
      source: 'blog-footer'
    },
    callback: () => {
      form.submit();
    }
  });
});

​
E-commerce Events

// Add to cart
track('Add to Cart', {
  props: {
    product: 'Premium Widget',
    sku: 'WIDGET-001',
    quantity: '2'
  }
});

// Checkout
track('Checkout Started', {
  props: {
    cart_value: '59.98'
  }
});

// Purchase
track('Purchase', {
  props: {
    order_id: 'ORD-12345',
    items: '3'
  },
  revenue: {
    amount: 59.98,
    currency: 'USD'
  }
});

​
Next Steps

Custom Properties

Add metadata and context to your events

Events API

Server-side event tracking

Build docs developers (and LLMs) love

Get started for freeTalk to us