Custom Event Tracking

Track custom goals, user interactions, and conversions with Plausible Analytics custom events

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:

Script Tag

// 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>

Tagged Links

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:

NPM

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

NPM Package

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']
  }
});

Script Tag

<!-- Custom file types -->
<script defer data-domain="example.com" 
  data-file-types="pdf,zip,mp4"
  src="https://plausible.io/js/script.file-downloads.js"></script>

<!-- Add to default types -->
<script defer data-domain="example.com" 
  data-add-file-types="sketch,fig"
  src="https://plausible.io/js/script.file-downloads.js"></script>

File downloads are tracked as “File Download” events with a url property:

{
  name: 'File Download',
  props: {
    url: 'https://example.com/documents/report.pdf'
  }
}

Outbound Links

Automatically track clicks on external links:

NPM

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