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

# Events and callbacks

> Observe Connect.js loading, user actions, errors, exits, and successful completion.

Connect.js exposes four callbacks. Each callback marks a different point in the widget lifecycle.

## Callback summary

| Callback    | Required | Called when                                                      | Arguments           |
| ----------- | -------- | ---------------------------------------------------------------- | ------------------- |
| `onSuccess` | Yes      | Account linking or a payment flow completes.                     | One result object   |
| `onClose`   | No       | The widget is hidden through a user exit, success, or `close()`. | None                |
| `onLoad`    | No       | The widget iframe mounts and loads.                              | None                |
| `onEvent`   | No       | A supported lifecycle or user-action event occurs.               | `eventName`, `data` |

## `onSuccess`

Account linking returns an object containing a short-lived code.

```javascript theme={null}
onSuccess: ({ code }) => sendCodeToBackend(code)
```

A payment flow returns charge data instead. Keep flow-specific handlers separate so the code does not assume one response shape for both.

## `onClose`

```javascript theme={null}
onClose: () => {
  setConnectOpen(false)
}
```

`close()` invokes this callback, including when the SDK closes after success.

## `onLoad`

Use `onLoad` to enable the trigger only after the widget is ready.

```javascript theme={null}
onLoad: () => {
  setLinkButtonEnabled(true)
}
```

## `onEvent`

```javascript theme={null}
onEvent: (eventName, data) => {
  console.log(eventName, data)
}
```

The current SDK maps widget messages to these event names:

| Event                  | Meaning                                                                 |
| ---------------------- | ----------------------------------------------------------------------- |
| `LOADED`               | The widget iframe loaded.                                               |
| `OPENED`               | The widget became visible.                                              |
| `EXIT`                 | The user exited the flow.                                               |
| `ERROR`                | The widget reported an error.                                           |
| `INSTITUTION_SELECTED` | The user selected an institution.                                       |
| `AUTH_METHOD_SWITCHED` | The user changed authentication method.                                 |
| `SUBMIT_CREDENTIALS`   | The user submitted the institution login step.                          |
| `SUBMIT_MFA`           | The user submitted a multi-factor authentication step.                  |
| `ACCOUNT_LINKED`       | The widget linked an account.                                           |
| `ACCOUNT_SELECTED`     | The user selected an account.                                           |
| `SUCCESS`              | The SDK received its account-linked or charge-complete success message. |

## Payload handling

Payload fields depend on the event and may include an institution, authentication method, error metadata, page name, selected-account count, timestamp, or the optional `reference` supplied during setup.

Read event data defensively:

```javascript theme={null}
onEvent: (eventName, data = {}) => {
  if (eventName === "INSTITUTION_SELECTED") {
    analytics.track("mono_institution_selected", {
      institutionId: data.institution?.id,
      authMethod: data.authMethod
    })
  }

  if (eventName === "ERROR") {
    errorTracker.captureMessage("Mono Connect error", {
      extra: {
        errorType: data.errorType,
        errorMessage: data.errorMessage,
        reference: data.reference
      }
    })
  }
}
```

<Warning>
  Do not record credentials, MFA values, BVNs, account numbers, or unreviewed full event payloads. Define an allowlist of fields for analytics and logs.
</Warning>

## Success semantics

`ACCOUNT_LINKED` is useful telemetry about widget progress. Use `onSuccess` to obtain the auth code and start the backend exchange. Treat the backend's successful exchange and persistence as application-level completion.