> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ghostlyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom events

> Track user interactions beyond pageviews using the GhostlyX JavaScript API.

## Firing a custom event

Call the global `ghostlyx()` function after the tracking script has loaded:

```js theme={"dark"}
ghostlyx('event', 'Button clicked')
```

The event name is a free-form string. Choose names that are meaningful to your team. Event names are case-sensitive.

## Adding properties

Pass an object as the third argument to attach properties to the event:

```js theme={"dark"}
ghostlyx('event', 'Purchase', { revenue: 49.99, plan: 'pro' })
```

Properties must be strings or numbers. A maximum of 20 properties are supported per event. Properties appear in the goal detail view in the dashboard once a matching goal is created.

## Connecting events to goals

Events are only counted in the dashboard when a matching [Custom event goal](/analytics/goals) exists. Create a goal with the same event name in **Settings > Goals** to start seeing completions and conversion rates.

## SPA and deferred loading

If your script loads asynchronously, wrap event calls in a check to avoid errors before the script is ready:

```js theme={"dark"}
if (typeof ghostlyx === 'function') {
  ghostlyx('event', 'Sign up started')
}
```

## Server-side events

If you need to fire an event from your server (for example, after a payment is confirmed server-side), use the Events API instead of the JavaScript API. See [Server-side tracking](/developer/server-side-tracking) for details.