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

# Listen to SDK events

> Use $sleek.on() to react to widget lifecycle and authentication events, plus a full reference for every event the SDK emits

`$sleek.on()` lets you register callbacks that fire whenever the widget emits a lifecycle or authentication event — for example, when the widget opens, when a user navigates to a new screen, or when authentication completes. If you need to attach a listener before the `$sleek` object is available, you can also use `document.addEventListener` with the `sleek:` prefix on any event name.

## Register a listener

Call `$sleek.on(action, callback)` to register a function that runs whenever the specified event fires.

```javascript theme={"system"}
$sleek.on('open', function () {
  console.log('The widget was opened');
});

$sleek.on('close', function () {
  console.log('The widget was closed');
});
```

<ParamField path="body.action" type="string" required>
  The name of the event to listen for. See the [event reference](#event-reference) below for all available event names.
</ParamField>

<ParamField path="body.callback" type="function">
  A function to execute when the event fires. Some events pass a return value as the first argument — see the event table for details.
</ParamField>

## Listen before the SDK loads

If you need to attach a listener before the `$sleek` object is available — for example, in a script that runs earlier than the SDK — use the native `document.addEventListener` API with the `sleek:` prefix on the event name.

```javascript theme={"system"}
// Listen for the 'init' event before the SDK loads
window.document.addEventListener('sleek:init', function () {
  console.log('SDK has finished initializing');
}, false);

// Listen for navigation events before the SDK loads
window.document.addEventListener('sleek:navigation_after_enter', function (event) {
  console.log('Navigated to view:', event.detail);
}, false);
```

<Note>
  The `sleek:eventname` pattern mirrors every event in the table below. Replace `eventname` with the exact event name — for example, `sleek:open`, `sleek:user_auth_completed`.
</Note>

## Event reference

| Event                     | Return value   | Description                                                                                  |
| ------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `init`                    | —              | Fires once after the SDK finishes initializing                                               |
| `open`                    | —              | Fires after the widget is opened                                                             |
| `close`                   | —              | Fires after the widget is closed                                                             |
| `navigation_before_enter` | `current_view` | Fires before a new screen begins entering; receives the name of the incoming view            |
| `navigation_after_enter`  | `current_view` | Fires after the screen transition animation completes; receives the name of the current view |
| `widget_init`             | —              | Fires the first time the widget iframe finishes loading                                      |
| `user_auth_required`      | —              | Fires when the user attempts an action that requires authentication                          |
| `user_auth_start`         | —              | Fires after the authentication flow has started                                              |
| `user_auth_confirm`       | —              | Fires whenever the user must confirm their email address                                     |
| `user_auth_completed`     | —              | Fires after the authentication flow completes successfully                                   |
| `user_auth_error`         | —              | Fires whenever an authentication error occurs                                                |

## Code examples

### Track widget open and close

```javascript theme={"system"}
$sleek.on('open', function () {
  analytics.track('Sleekplan widget opened');
});

$sleek.on('close', function () {
  analytics.track('Sleekplan widget closed');
});
```

### React to navigation changes

```javascript theme={"system"}
$sleek.on('navigation_after_enter', function (currentView) {
  console.log('User navigated to:', currentView);
});
```

### Handle authentication events

```javascript theme={"system"}
$sleek.on('user_auth_required', function () {
  // The user tried to do something that needs a login
  console.log('Authentication required');
});

$sleek.on('user_auth_completed', function () {
  console.log('User successfully authenticated');
});

$sleek.on('user_auth_error', function () {
  console.warn('Authentication failed');
});
```

### Wait for the widget to be ready

```javascript theme={"system"}
$sleek.on('widget_init', function () {
  // Safe to call widget methods that depend on the iframe being loaded
  console.log('Widget is ready');
});
```

### Listen before the SDK script loads

```javascript theme={"system"}
// Place this before the $sleek SDK script tag
window.document.addEventListener('sleek:init', function () {
  console.log('SDK initialized — setting up user now');
  $sleek.setUser({ mail: 'user@example.com', id: '42' });
}, false);
```