Skip to content

Custom events

Custom events record specific interactions beyond pageviews: a CTA click, a form submission, a video play, an in-app action. Track anything that maps to real user intent.

Make sure s.js is installed on the page. See Install the tracking script.

Three ways to fire an event

1. JavaScript API

Call window.statable.t() with the event name from anywhere in your code (a click handler, router hook, fetch callback):

<script>
  document.querySelector('#newsletter-form').addEventListener('submit', () => {
    window.statable.t('Newsletter Signup')
  })
</script>

The first argument is the event name. That's all that's required. Names are free-form and case-sensitive. Pick a convention (Title Case, Verb Noun) and stick with it.

To attach context, pass a properties object as the second argument:

window.statable.t('Newsletter Signup', { source: 'footer', plan: 'free' })

See Custom properties for the full reference on properties.

2. HTML data-attribute

Add data-statable-event to any element you want to track. s.js attaches a single click listener to document and walks up the DOM from the click target. The attribute works on <button>, <a>, <div>, any element:

<button type="button" class="share-fab" data-statable-event="Share">
  <span class="fab-tooltip">Share This Tool</span>
  <svg>...</svg>
</button>

<a href="/pricing"
   data-statable-event="View Pricing"
   data-statable-tier="pro">
  Pro plan
</a>

The walker checks up to three DOM levels from the click target, so wrapping the trigger in extra markup still works:

<button data-statable-event="Buy Now">
  <span class="icon"><svg>...</svg></span>
  <span class="label">Buy now</span>
</button>

Clicking the inner <span> or <svg> still fires Buy Now. If your trigger is nested deeper than three levels, attach the attribute closer to the click target.

3. Form submit

Put data-statable-event on a <form> element to track its submit:

<form action="/api/subscribe" method="post" data-statable-event="Newsletter Signup">
  <input type="email" name="email" required>
  <button type="submit">Subscribe</button>
</form>

The event fires on the form's submit event. If your form uses AJAX and prevents the default submit, fire the event manually from your success handler with window.statable.t('Newsletter Signup') instead.

Auto-tracked events

s.js records two custom events without any markup:

  • Outbound Link Click: fires when an <a> is clicked and its host differs from the current page. Destination URL is attached as a property.
  • File Download: fires when an <a> is clicked and any of these holds:
    • href ends in .pdf, .zip, .rar, .gz, .tar, .7z, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .csv, .exe, .dmg, .iso, .mp3, .mp4, .avi, or .mov
    • It has the HTML download attribute
    • Its type attribute is anything other than text/html

Both appear in your dashboard alongside manual events.

Viewing events

Go to Custom Analytics → Custom Events. Each row shows event name, total count, unique visitors, and conversion rate against pageviews in the same range.

Click an event to drill into its property breakdown, or use it as a filter to scope every other widget to sessions that fired it.

Reserved event names

pageview and engagement are reserved for Statable's automatic events. Calling window.statable.t('pageview') or putting data-statable-event="engagement" on an element will collide with SDK reporting and produce incorrect counts. Use any other name (Page Loaded, Engaged, View Article).

Next steps

Ready to take control of your web analytics? Try Statable free for 30 days — no credit card required, full feature access, GDPR-compliant by default. Start your free trial or view a live demo.