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

# Events and Lifecycle

> Event system, status transitions, and instance lifecycle management.

The `Deposit` class emits events during the deposit flow. Use `on()` and `off()` to subscribe and unsubscribe.

## Events

### complete

Fired when the payment completes successfully. The handler receives a `DepositResult`.

```typescript theme={null}
deposit.on('complete', (result: DepositResult) => {
  console.log('Transfer ID:', result.transfer.id);
  console.log('Status:', result.transfer.status);
});
```

### error

Fired when the deposit flow fails. The handler receives a `DepositError`.

```typescript theme={null}
deposit.on('error', (error: DepositError) => {
  console.error('Transfer failed:', error.code, error.message);
});
```

### close

Fired when the transfer iframe is dismissed (user tapped backdrop, pressed Escape, or the flow was closed programmatically).

```typescript theme={null}
deposit.on('close', () => {
  console.log('Transfer closed');
});
```

### status-change

Fired on every status transition. The handler receives the new `DepositStatus`.

```typescript theme={null}
deposit.on('status-change', (status: DepositStatus) => {
  console.log('Status:', status);
});
```

### resize

Fired only when the resolved presentation is `embedded`. Blink reports the rendered content height and its width design envelope. The SDK has already resized the inline iframe; use this event when your outer panel should follow it.

```typescript theme={null}
const maxHeightPx = 640;

deposit.on('resize', ({ heightPx, preferredWidthPx, minWidthPx }) => {
  panel.style.height = `${Math.min(heightPx, maxHeightPx)}px`;

  if (preferredWidthPx !== undefined) {
    panel.style.width = `${preferredWidthPx}px`;
  }

  console.log('Minimum supported width:', minWidthPx);
});
```

| Field | Type | Description |
| - | - | - |
| `heightPx` | `number` | Blink's current rendered content height. It can change on every frame of an internal screen transition. |
| `preferredWidthPx` | `number \| undefined` | Preferred panel width. Currently 440px. |
| `minWidthPx` | `number \| undefined` | Minimum supported active width. Currently 320px. |

> [!WARNING]
>
> Do not apply a CSS transition to reported height changes. Blink already animates its internal height. Width may transition because the width hints are stable values.

No `resize` event fires for the overlay presentation, including when an embedded request resolves to the overlay on mobile. See [Embed Blink in an aggregator](https://docs.blink.cash/integration/embedded-deposit-sdk.md).

## Status transitions

```mermaid theme={null}
stateDiagram-v2
    idle --> signerLoading: requestDeposit()
    signerLoading --> iframeActive: Signer responded
    signerLoading --> errorState: Signer failed
    iframeActive --> completed: Payment complete
    iframeActive --> errorState: Flow timeout / dismissed
    completed --> signerLoading: requestDeposit()
    errorState --> signerLoading: requestDeposit()
    state "signer-loading" as signerLoading
    state "iframe-active" as iframeActive
    state "error" as errorState
```

| Status | Meaning |
| - | - |
| `idle` | No active flow. Initial state and state after `close()` or `destroy()`. |
| `signer-loading` | The SDK is calling the merchant signer endpoint. |
| `iframe-active` | The hosted flow iframe is open. Waiting for the user to complete payment. |
| `completed` | Transfer succeeded. `result` is available. |
| `error` | Something failed. `error` is available. |

## Subscribing and unsubscribing

```typescript theme={null}
const onComplete = (result: DepositResult) => {
  updateUI(result);
};

// Subscribe
deposit.on('complete', onComplete);

// Unsubscribe
deposit.off('complete', onComplete);
```

Both `on()` and `off()` return `this` for chaining:

```typescript theme={null}
deposit
  .on('complete', handleComplete)
  .on('error', handleError)
  .on('close', handleClose);
```

## Lifecycle management

### close()

Closes the transfer iframe and resets status to `idle`. Fires the `close` event. Does not destroy the instance. You can call `requestDeposit()` again.

If a flow is active, `close()` also rejects its pending `requestDeposit()` promise with `DEPOSIT_DISMISSED`. This lets an embedded host handle its own back button and Blink's dismissal through one error branch.

```typescript theme={null}
deposit.close();
```

### destroy()

Closes the iframe, removes all event listeners, and marks the instance as destroyed. Subsequent calls to `requestDeposit()` will reject with `INVALID_REQUEST`.

Call this when the component unmounts or the page unloads.

```typescript theme={null}
// Vanilla JS, on page unload
window.addEventListener('beforeunload', () => deposit.destroy());

// React, handled automatically by useBlinkDeposit
```

> [!WARNING]
>
> Always call `destroy()` when the transfer is no longer needed to prevent memory leaks from lingering event listeners.

## React lifecycle

The `useBlinkDeposit` hook manages the `Deposit` instance lifecycle automatically:

* Creates the instance on first render.
* Subscribes to `status-change`, `complete`, and `error` events.
* Cleans up all subscriptions and calls `destroy()` on unmount.

You do not need to call `destroy()` manually when using the React hook.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.