> ## 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.

## 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'` |


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