---
title: Custom Events
description: Track button clicks, form submissions, and other user interactions
url: https://www.supalytics.co/docs/custom-events
---



Track user interactions beyond pageviews - button clicks, sign-ups, purchases, and more.

## Method 1: HTML Data Attributes

The simplest way to track events - no JavaScript required. Use `data-supalytics-e` (e = event):

```html
<button data-supalytics-e="signup">Sign Up</button>
```

### With Metadata

Add additional data using `data-supalytics-e-*` attributes:

```html
<button
  data-supalytics-e="purchase"
  data-supalytics-e-price="49"
  data-supalytics-e-plan="pro"
  data-supalytics-e-currency="USD">
    Buy Now
</button>
```

This tracks a `purchase` event with metadata `{ price: "49", plan: "pro", currency: "USD" }`.

***

## Method 2: JavaScript API

For more control, use `window.supalytics.trackEvent()`:

```javascript
window.supalytics.trackEvent('signup_click')
```

## With Metadata

Add metadata to your events:

```javascript
window.supalytics.trackEvent('purchase', {
  plan: 'pro',
  price: 29,
  currency: 'USD'
})
```

## Common Examples

### Button Click

```javascript
document.querySelector('#cta-button').addEventListener('click', () => {
  window.supalytics.trackEvent('cta_click', { location: 'hero' })
})
```

### Form Submission

```javascript
document.querySelector('form').addEventListener('submit', () => {
  window.supalytics.trackEvent('form_submit', { form: 'contact' })
})
```

### React

```jsx
function SignupButton() {
  const handleClick = () => {
    window.supalytics.trackEvent('signup_click', { source: 'navbar' })
  }

  return <button onClick={handleClick}>Sign Up</button>
}
```

### Next.js

```jsx
'use client'

export function DownloadButton() {
  const handleClick = () => {
    if (typeof window !== 'undefined' && window.supalytics) {
      window.supalytics.trackEvent('download', { file: 'guide.pdf' })
    }
  }

  return <button onClick={handleClick}>Download</button>
}
```

## Rules

* **Event names**: lowercase letters, numbers, underscores, and hyphens only (max 64 characters)
* **Metadata keys**: `data-supalytics-e-plan-type` becomes `plan_type`
* **Metadata values**: strings, numbers, or booleans (max 255 characters)
* **Limit**: maximum 10 metadata attributes per event

## Viewing Events

Events appear in the **Events** card on your dashboard. Hover on any event to see:

* **Triggered** - Total number of times the event was fired
* **Visitors** - Unique visitors who triggered this event, and what percentage of your total visitors that represents
* **Revenue** - Revenue attributed to visitors who triggered this event
* **Revenue/visitor** - Average revenue per visitor who triggered this event

## Method 3: Server-Side API

Track events from your backend using the [Server-Side Events API](/docs/api/server-side-events). Useful for webhooks, cron jobs, or any server code.

```javascript
await fetch("https://api.supalytics.co/v1/events", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.SUPALYTICS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "subscription_created",
    visitor_id: user.visitorId,
    metadata: { plan: "pro" },
  }),
});
```

[Get an API key](/docs/api/authentication) to get started.

## Client API Reference

```typescript
window.supalytics.trackEvent(
  eventName: string,
  metadata?: Record<string, unknown>
): Promise<void>
```

| Parameter   | Type   | Description                  |
| ----------- | ------ | ---------------------------- |
| `eventName` | string | Name of the event (required) |
| `metadata`  | object | Optional key-value metadata  |


---

## Other Documentation

- [Autocapture](https://www.supalytics.co/llms/docs/autocapture)
- [Backfill Existing Subscriptions](https://www.supalytics.co/llms/docs/backfill-existing-subscriptions)
- [Block Your Own Traffic](https://www.supalytics.co/llms/docs/block-your-traffic)
- [CLI](https://www.supalytics.co/llms/docs/cli)
- [Features](https://www.supalytics.co/llms/docs/features)
- [Conversion Funnels](https://www.supalytics.co/llms/docs/funnels)
- [Introduction](https://www.supalytics.co/llms/docs)
- [Install Script](https://www.supalytics.co/llms/docs/install-script)
- [MRR Tracking](https://www.supalytics.co/llms/docs/mrr-tracking)
- [Revenue Attribution](https://www.supalytics.co/llms/docs/revenue-attribution)
- [Agent Skills](https://www.supalytics.co/llms/docs/skills)
- [Tracking Modes](https://www.supalytics.co/llms/docs/tracking-modes)
- [Visitor Journey](https://www.supalytics.co/llms/docs/visitor-journey)
- [Annotations](https://www.supalytics.co/llms/docs/api/annotations)
- [Error Codes](https://www.supalytics.co/llms/docs/api/errors)
- [Events (Read)](https://www.supalytics.co/llms/docs/api/events)
- [API Reference](https://www.supalytics.co/llms/docs/api)
- [Journeys](https://www.supalytics.co/llms/docs/api/journeys)
- [Query API](https://www.supalytics.co/llms/docs/api/query)
- [Realtime API](https://www.supalytics.co/llms/docs/api/realtime)
- [Revenue Attribution API](https://www.supalytics.co/llms/docs/api/revenue-attribution)
- [Events (Write)](https://www.supalytics.co/llms/docs/api/server-side-events)