Custom events

Track user interactions beyond page views.

Basic usage

Use the global analytics object to track events:

// Track a simple event
window.analytics.track('signup_click');

// Track an event with properties
window.analytics.track('purchase', {
  plan: 'pro',
  value: 29
});

Common examples

Button clicks

<button onclick="window.analytics.track('cta_click', { button: 'hero' })">
  Get Started
</button>

Form submissions

<form onsubmit="window.analytics.track('form_submit', { form: 'contact' })">
  <!-- form fields -->
  <button type="submit">Send</button>
</form>

Newsletter signup

function handleSubscribe() {
  // Your subscription logic...

  window.analytics.track('newsletter_signup', {
    source: 'footer'
  });
}

Video engagement

video.addEventListener('play', () => {
  window.analytics.track('video_play', { video: 'demo' });
});

video.addEventListener('ended', () => {
  window.analytics.track('video_complete', { video: 'demo' });
});

E-commerce

// Add to cart
window.analytics.track('add_to_cart', {
  product: 'T-Shirt',
  price: 25,
  currency: 'USD'
});

// Purchase complete
window.analytics.track('purchase', {
  value: 75,
  items: 3
});

React / Next.js

// Declare the global type
declare global {
  interface Window {
    analytics: {
      track: (event: string, props?: Record<string, any>) => void;
      pageview: () => void;
    };
  }
}

// Use in components
export function SignupButton() {
  const handleClick = () => {
    window.analytics.track('signup_click', { location: 'header' });
    // Continue with signup...
  };

  return (
    <button onClick={handleClick}>
      Sign Up
    </button>
  );
}

Event properties

Properties help you segment and analyze events. Keep them simple:

  • Use lowercase names with underscores: button_click
  • Keep property values short and categorical
  • Don't include personal data (emails, names, etc.)
  • Limit to 5-10 properties per event

Privacy note

Never include personal identifiable information (PII) in event names or properties. This includes emails, names, phone numbers, or any data that could identify a specific person.

Using events with goals

Custom events can be used as conversion goals. For example, if you track a purchase event, you can create a goal that triggers when this event fires.

Go to Settings → Goals → Add goal → Select "Custom event" and enter the event name. Learn more in our goals documentation.

Related resources