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

# Widget Light Events

> Subscribe to widget events with @lifi/widget-light

Widget Light provides a typed event system that lets you react to user interactions, route execution progress, wallet changes, and more. Events are forwarded from the widget iframe to your host application via `postMessage`.

## Subscribing to Events

Use the `useWidgetLightEvents()` hook to get the event emitter, then subscribe with `on` and unsubscribe with `off`:

```tsx theme={"system"}
import {
  useWidgetLightEvents,
  WidgetLightEvent,
} from '@lifi/widget-light'
import { useEffect } from 'react'

function TransactionTracker() {
  const events = useWidgetLightEvents()

  useEffect(() => {
    const onCompleted = (data: unknown) => {
      console.log('Route completed:', data)
    }
    events.on(WidgetLightEvent.RouteExecutionCompleted, onCompleted)
    return () => {
      events.off(WidgetLightEvent.RouteExecutionCompleted, onCompleted)
    }
  }, [events])

  return null
}
```

### Key Details

* **Module-level singleton** -- the event bus is a module-level singleton, so `useWidgetLightEvents()` can be called from any component. It does not need to be co-located with `<LiFiWidgetLight>` and does not require any provider wrapping.

* **Subscription-tracked forwarding** -- events are only forwarded from the iframe when at least one host-side listener is subscribed. When you call `events.on(eventName, handler)`, the host sends a `WIDGET_EVENT_SUBSCRIBE` message to the iframe. When the last listener for an event is removed, the host sends `WIDGET_EVENT_UNSUBSCRIBE`. This avoids unnecessary `postMessage` traffic.

* **Stable reference** -- the emitter returned by `useWidgetLightEvents()` is a stable module-level object. You do not need to memoize it or add it to dependency arrays (though it is safe to do so).

## Tracking Route Execution

A common use case is tracking the lifecycle of a swap or bridge route:

```tsx theme={"system"}
import {
  useWidgetLightEvents,
  WidgetLightEvent,
  type WidgetLightRouteExecutionUpdate,
} from '@lifi/widget-light'
import { useEffect } from 'react'

function RouteTracker() {
  const events = useWidgetLightEvents()

  useEffect(() => {
    const onStart = (data: unknown) => {
      console.log('Route started:', data)
    }
    const onUpdate = (data: WidgetLightRouteExecutionUpdate) => {
      console.log('Step updated:', data.route, data.action)
    }
    const onComplete = (data: unknown) => {
      console.log('Route completed:', data)
    }
    const onFail = (data: WidgetLightRouteExecutionUpdate) => {
      console.error('Route failed:', data.route, data.action)
    }

    events.on(WidgetLightEvent.RouteExecutionStarted, onStart)
    events.on(WidgetLightEvent.RouteExecutionUpdated, onUpdate)
    events.on(WidgetLightEvent.RouteExecutionCompleted, onComplete)
    events.on(WidgetLightEvent.RouteExecutionFailed, onFail)

    return () => {
      events.off(WidgetLightEvent.RouteExecutionStarted, onStart)
      events.off(WidgetLightEvent.RouteExecutionUpdated, onUpdate)
      events.off(WidgetLightEvent.RouteExecutionCompleted, onComplete)
      events.off(WidgetLightEvent.RouteExecutionFailed, onFail)
    }
  }, [events])

  return null
}
```

## Event Reference

### Route Execution Events

| Event                     | Payload Type                      | Description                                                 |
| ------------------------- | --------------------------------- | ----------------------------------------------------------- |
| `RouteExecutionStarted`   | `unknown`                         | A route has started executing                               |
| `RouteExecutionUpdated`   | `WidgetLightRouteExecutionUpdate` | Step progress update (contains `route` and `action`)        |
| `RouteExecutionCompleted` | `unknown`                         | Route completed successfully                                |
| `RouteExecutionFailed`    | `WidgetLightRouteExecutionUpdate` | Route execution failed (contains `route` and `action`)      |
| `RouteSelected`           | `WidgetLightRouteSelected`        | User selected a route (contains `route` and `routes` array) |
| `RouteHighValueLoss`      | `WidgetLightRouteHighValueLoss`   | High value loss detected on a route                         |

### Form and Selection Events

| Event                           | Payload Type                    | Description                                                             |
| ------------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
| `SourceChainTokenSelected`      | `WidgetLightChainTokenSelected` | Source chain/token changed (contains `chainId` and `tokenAddress`)      |
| `DestinationChainTokenSelected` | `WidgetLightChainTokenSelected` | Destination chain/token changed (contains `chainId` and `tokenAddress`) |
| `FormFieldChanged`              | `WidgetLightFormFieldChanged`   | Any form field changed (contains `fieldName`, `newValue`, `oldValue`)   |
| `TokenSearch`                   | `WidgetLightTokenSearch`        | User searched for a token (contains `value` and `tokens`)               |

### Wallet Events

| Event                | Payload Type                    | Description                                                                                                  |
| -------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `WalletConnected`    | `WidgetLightWalletConnected`    | Wallet connected (contains `address`, `chainId`, `chainType`, `connectorId`, `connectorName`)                |
| `WalletDisconnected` | `WidgetLightWalletDisconnected` | Wallet disconnected (contains `chainType` and optional `address`, `chainId`, `connectorId`, `connectorName`) |

### UI Events

| Event                 | Payload Type                | Description                                                  |
| --------------------- | --------------------------- | ------------------------------------------------------------ |
| `PageEntered`         | `string`                    | User navigated to a page (page name as string)               |
| `WidgetExpanded`      | `boolean`                   | Widget expanded or collapsed (drawer variant)                |
| `SendToWalletToggled` | `boolean`                   | Send-to-wallet toggle changed                                |
| `AvailableRoutes`     | `unknown[]`                 | Routes have been fetched and are available                   |
| `ContactSupport`      | `WidgetLightContactSupport` | User clicked contact support (contains optional `supportId`) |

### Settings and Preferences Events

| Event                         | Payload Type                             | Description                                                                                       |
| ----------------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `SettingUpdated`              | `WidgetLightSettingUpdated`              | User changed a setting (contains `setting`, `newValue`, `oldValue`, `newSettings`, `oldSettings`) |
| `ChainPinned`                 | `WidgetLightChainPinned`                 | Chain pinned or unpinned (contains `chainId` and `pinned`)                                        |
| `LowAddressActivityConfirmed` | `WidgetLightLowAddressActivityConfirmed` | Low activity address confirmed (contains `address` and `chainId`)                                 |

## Payload Types

All payload types are exported from `@lifi/widget-light`:

```tsx theme={"system"}
import type {
  WidgetLightRouteExecutionUpdate,
  WidgetLightRouteSelected,
  WidgetLightRouteHighValueLoss,
  WidgetLightChainTokenSelected,
  WidgetLightFormFieldChanged,
  WidgetLightWalletConnected,
  WidgetLightWalletDisconnected,
  WidgetLightContactSupport,
  WidgetLightSettingUpdated,
  WidgetLightChainPinned,
  WidgetLightTokenSearch,
  WidgetLightLowAddressActivityConfirmed,
} from '@lifi/widget-light'
```

<Note>
  Route-carrying payloads (`WidgetLightRouteExecutionUpdate`, `WidgetLightRouteSelected`) use `unknown` for the `route` field because the full route type from `@lifi/sdk` is not available in Widget Light's zero-dependency type system. Cast to your local `@lifi/sdk` types if you need typed access to route properties.
</Note>

## WidgetLightEvent Enum

All event names are available as the `WidgetLightEvent` enum:

```tsx theme={"system"}
import { WidgetLightEvent } from '@lifi/widget-light'

// Use enum values for type-safe event names
events.on(WidgetLightEvent.RouteExecutionCompleted, handler)

// Or use string literals directly
events.on('routeExecutionCompleted', handler)
```

| Enum Member                                      | String Value                      |
| ------------------------------------------------ | --------------------------------- |
| `WidgetLightEvent.AvailableRoutes`               | `'availableRoutes'`               |
| `WidgetLightEvent.ChainPinned`                   | `'chainPinned'`                   |
| `WidgetLightEvent.ContactSupport`                | `'contactSupport'`                |
| `WidgetLightEvent.DestinationChainTokenSelected` | `'destinationChainTokenSelected'` |
| `WidgetLightEvent.FormFieldChanged`              | `'formFieldChanged'`              |
| `WidgetLightEvent.LowAddressActivityConfirmed`   | `'lowAddressActivityConfirmed'`   |
| `WidgetLightEvent.PageEntered`                   | `'pageEntered'`                   |
| `WidgetLightEvent.RouteExecutionCompleted`       | `'routeExecutionCompleted'`       |
| `WidgetLightEvent.RouteExecutionFailed`          | `'routeExecutionFailed'`          |
| `WidgetLightEvent.RouteExecutionStarted`         | `'routeExecutionStarted'`         |
| `WidgetLightEvent.RouteExecutionUpdated`         | `'routeExecutionUpdated'`         |
| `WidgetLightEvent.RouteHighValueLoss`            | `'routeHighValueLoss'`            |
| `WidgetLightEvent.RouteSelected`                 | `'routeSelected'`                 |
| `WidgetLightEvent.SendToWalletToggled`           | `'sendToWalletToggled'`           |
| `WidgetLightEvent.SettingUpdated`                | `'settingUpdated'`                |
| `WidgetLightEvent.SourceChainTokenSelected`      | `'sourceChainTokenSelected'`      |
| `WidgetLightEvent.TokenSearch`                   | `'tokenSearch'`                   |
| `WidgetLightEvent.WidgetExpanded`                | `'widgetExpanded'`                |
| `WidgetLightEvent.WalletConnected`               | `'walletConnected'`               |
| `WidgetLightEvent.WalletDisconnected`            | `'walletDisconnected'`            |