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

# Custom Events

> Listen to calculator widget events for analytics and integration

The widget dispatches custom events that bubble from the host element, allowing you to integrate with analytics, tracking systems, or your existing JavaScript.

## Event Reference

All events are dispatched on the widget's host element and bubble up to `document`. Use standard `addEventListener()` to listen for them.

| Event                      | Payload                                | When fired                                  |
| :------------------------- | :------------------------------------- | :------------------------------------------ |
| `cdn-calculator:ready`     | `{ countries: Country[] }`             | Widget initialized and country data loaded  |
| `cdn-calculator:calculate` | `{ country, currency, gross, period }` | User clicked calculate (before API request) |
| `cdn-calculator:result`    | `Result`                               | Calculation completed successfully          |
| `cdn-calculator:view`      | `{ view: 'form' \| 'result' }`         | User switched between form and result views |
| `cdn-calculator:error`     | `ApiError`                             | API request failed or validation error      |

***

## Event Details

### cdn-calculator:ready

Fired when the widget is fully loaded and ready for user interaction.

```javascript JavaScript theme={null}
mount.addEventListener('cdn-calculator:ready', e => {
  console.log('Widget ready with', e.detail.countries.length, 'countries');
});
```

### cdn-calculator:calculate

Fired when user submits the form, before making the API request.

```javascript JavaScript theme={null}
mount.addEventListener('cdn-calculator:calculate', e => {
  console.log('Calculating for', e.detail.country.name, 'at', e.detail.gross);
  analytics.track('salary_calculation_started', e.detail);
});
```

### cdn-calculator:result

Fired when calculation completes successfully.

```javascript JavaScript theme={null}
mount.addEventListener('cdn-calculator:result', e => {
  console.log('Total employer cost:', e.detail.totalEmployerCost);
});
```

### cdn-calculator:view

Fired when user navigates between form and result views.

```javascript JavaScript theme={null}
mount.addEventListener('cdn-calculator:view', e => {
  console.log('User switched to', e.detail.view, 'view');
});
```

### cdn-calculator:error

Fired when an error occurs (invalid API key, network issues, etc.).

```javascript JavaScript theme={null}
mount.addEventListener('cdn-calculator:error', e => {
  console.error('Widget error:', e.detail.message);
});
```

***

## Integration Example

**Google Analytics 4:**

```javascript JavaScript theme={null}
mount.addEventListener('cdn-calculator:result', e => {
  gtag('event', 'salary_calculated', {
    country: e.detail.country.code,
    gross_amount: e.detail.grossAmount.amount,
    employer_cost: e.detail.totalEmployerCost.amount
  });
});
```

***

## Event Payload Structures

### cdn-calculator:ready

```javascript JavaScript theme={null}
{
  countries: [
    {
      code: "CO",
      name: "Colombia",
      regions: [
        { code: "AMA", name: "Amazonas" },
        { code: "ANT", name: "Antioquia" }
      ]
    }
  ]
}
```

### cdn-calculator:calculate

```javascript JavaScript theme={null}
{
  country: {
    code: "CO",
    name: "Colombia"
  },
  currency: {
    code: "COP",
    name: "Colombian Peso"
  },
  gross: 2000000,
  period: "monthly"
}
```

### cdn-calculator:result

```javascript JavaScript theme={null}
{
  grossAmount: {
    amount: 200000000,  // in cents
    currency: "COP"
  },
  netAmount: {
    amount: 142824527,
    currency: "COP"
  },
  deductions: [
    {
      name: "Pension Fund",
      isStatutory: true,
      amount: {
        amount: 8000000,
        currency: "COP"
      }
    }
  ],
  employerContributions: [
    {
      name: "Pension Fund",
      isStatutory: true,
      amount: {
        amount: 24000000,
        currency: "COP"
      }
    }
  ],
  totalEmployerCost: {
    amount: 43044000,
    currency: "COP"
  },
  country: {
    code: "CO",
    name: "Colombia"
  }
}
```

### cdn-calculator:view

```javascript JavaScript theme={null}
{
  view: "form" | "result"
}
```

### cdn-calculator:error

```javascript JavaScript theme={null}
{
  message: "Unable to load calculator. Please ensure your key is valid.",
  status: 401,
  code: "UNAUTHORIZED"
}
```

<Note>
  All monetary amounts are returned in cents to avoid floating-point precision issues. Divide by 100 to get the actual currency amount.
</Note>