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

> Stay up-to-date with widget events

**LI.FI Widget** provides a `useWidgetEvents` hook that lets you subscribe to a series of widget events and helps you retrieve helpful information about executing routes, track bridge and swap progress, track selection of chains and tokens, interactions with specific UI elements, and more.

We continue working on extending available events and if you are interested in a specific event, reach out via our [support](https://help.li.fi).

To minimize unnecessary re-renders and prevent potential glitches in the main Widget component, please integrate the `useWidgetEvents` hook outside of the component where the main `LiFiWidget` is integrated.

Example of how to subscribe to widget events:

```typescript theme={"system"}
import type { Route, ExecutionAction } from '@lifi/sdk';
import type { RouteExecutionUpdate, RouteHighValueLossUpdate } from '@lifi/widget';
import { useWidgetEvents, WidgetEvent } from '@lifi/widget';
import { useEffect } from 'react';

export const WidgetEventsExample = () => {
  const widgetEvents = useWidgetEvents();

  // ...

  useEffect(() => {
    const onRouteExecutionStarted = (route: Route) => {
      // console.log('onRouteExecutionStarted fired.');
    };
    const onRouteExecutionUpdated = (update: RouteExecutionUpdate) => {
      // console.log('onRouteExecutionUpdated fired.');
    };
    const onRouteExecutionCompleted = (route: Route) => {
      // console.log('onRouteExecutionCompleted fired.');
    };
    const onRouteExecutionFailed = (update: RouteExecutionUpdate) => {
      // console.log('onRouteExecutionFailed fired.');
    };
    const onRouteHighValueLoss = (update: RouteHighValueLossUpdate) => {
      // console.log('onRouteHighValueLoss continued.');
    };
    
    widgetEvents.on(WidgetEvent.RouteExecutionStarted, onRouteExecutionStarted);
    widgetEvents.on(WidgetEvent.RouteExecutionUpdated, onRouteExecutionUpdated);
    widgetEvents.on(WidgetEvent.RouteExecutionCompleted, onRouteExecutionCompleted);
    widgetEvents.on(WidgetEvent.RouteExecutionFailed, onRouteExecutionFailed);
    widgetEvents.on(WidgetEvent.RouteHighValueLoss, onRouteHighValueLoss);
    
    return () => widgetEvents.removeAllListeners();
  }, [widgetEvents]);

  // ...
  
  // Return null because it's an example
  return null;
};
```

## List of events

Here is the list of all available events:

**AvailableRoutes**

* Type: *Route\[]*

The event fires when available routes are returned after the user has selected source and destination tokens, entered an amount, and requested the routes.

**RouteSelected**

* Type: *RouteSelected*

The event fires when the user selects a specific route from the list of available routes.

**RouteExecutionStarted**

* Type: *Route*

The event fires when the user clicks on the Start swapping or Start bridging button.

**RouteExecutionUpdated**

* Type: *RouteExecutionUpdate*

The event fires when there is an update to the Route object during execution.

**RouteExecutionCompleted**

* Type: *Route*

The event fires when the execution is completed successfully.

**RouteExecutionFailed**

* Type: *RouteExecutionUpdate*

The event fires when the execution has failed.

**RouteHighValueLoss**

* Type: *RouteHighValueLossUpdate*

The event fires when the High Value Loss bottom sheet appears on the screen.

**ContactSupport**

* Type: *ContactSupport*

The event fires when the user clicks on the Contact support button on the Transaction Details page.

**SourceChainTokenSelected**

* Type: *ChainTokenSelected*

The event fires when the user selects the source chain and token.

**DestinationChainTokenSelected**

* Type: *ChainTokenSelected*

The event fires when the user selects the destination chain and token.

**SendToWalletToggled**

* Type: *boolean*

The event fires when the user clicks on the wallet icon next to the action button on the main page to show/hide the destination wallet selection UI.

**WidgetExpanded**

* Type: *boolean*

The event fires when the side panel with routes is shown to the user. Only available in the `wide` widget variant.

**PageEntered**

* Type: *NavigationRouteType*

The event fires when the user navigates to a page in the widget.

**FormFieldChanged**

* Type: *FormFieldChanged*

The event fires whenever a form value is changed in the widget.

**SettingUpdated**

* Type: *SettingUpdated*

The event fires whenever a setting is updated in the widget.

**TokenSearch**

* Type: *TokenSearch*

The event fires when the user searches for a token (includes the query value and the matched token results).

**LowAddressActivityConfirmed**

* Type: *LowAddressActivityConfirmed*

The event fires when the user confirms proceeding despite a low address activity warning for the specified address and chain.

**ChainPinned**

* Type: *ChainPinned*

The event fires when the user pins or unpins a chain in the UI.

**Routes**: Some of the events here present information about routes. A route is the LI.FI way of presenting a quote on an exchange/transfer. A route is a collection of steps, transactions and costs associated with that transfer. In the Widget we present a set of routes that the user can select from. Once selected the execution of that route can begin and the user will be guided through the steps required to complete that route. The route events above can help track a route status.

## Widget Events types

Properties and types of the `useWidgetEvents` hook.

```typescript theme={"system"}
enum WidgetEvent {
  AvailableRoutes = 'availableRoutes',
  ChainPinned = 'chainPinned',
  ContactSupport = 'contactSupport',
  DestinationChainTokenSelected = 'destinationChainTokenSelected',
  FormFieldChanged = 'formFieldChanged',
  LowAddressActivityConfirmed = 'lowAddressActivityConfirmed',
  PageEntered = 'pageEntered',
  RouteExecutionCompleted = 'routeExecutionCompleted',
  RouteExecutionFailed = 'routeExecutionFailed',
  RouteExecutionStarted = 'routeExecutionStarted',
  RouteExecutionUpdated = 'routeExecutionUpdated',
  RouteHighValueLoss = 'routeHighValueLoss',
  RouteSelected = 'routeSelected',
  SendToWalletToggled = 'sendToWalletToggled',
  SettingUpdated = 'settingUpdated',
  SourceChainTokenSelected = 'sourceChainTokenSelected',
  TokenSearch = 'tokenSearch',
  WidgetExpanded = 'widgetExpanded',
}

type WidgetEvents = {
  availableRoutes: (data: Route[]) => void
  chainPinned: (data: ChainPinned) => void
  contactSupport: (data: ContactSupport) => void
  destinationChainTokenSelected: (data: ChainTokenSelected) => void
  formFieldChanged: (data: FormFieldChanged) => void
  lowAddressActivityConfirmed: (data: LowAddressActivityConfirmed) => void
  pageEntered: (data: NavigationRouteType) => void
  routeExecutionCompleted: (data: Route) => void
  routeExecutionFailed: (data: RouteExecutionUpdate) => void
  routeExecutionStarted: (data: Route) => void
  routeExecutionUpdated: (data: RouteExecutionUpdate) => void
  routeHighValueLoss: (data: RouteHighValueLossUpdate) => void
  routeSelected: (data: RouteSelected) => void
  sendToWalletToggled: (data: boolean) => void
  settingUpdated: (data: SettingUpdated) => void
  sourceChainTokenSelected: (data: ChainTokenSelected) => void
  tokenSearch: (data: TokenSearch) => void
  widgetExpanded: (data: boolean) => void
}

type ContactSupport = {
  supportId?: string
}

type RouteHighValueLossUpdate = {
  fromAmountUSD: number
  toAmountUSD: number
  gasCostUSD?: number
  feeCostUSD?: number
  valueLoss: number
}

// `Route` and `ExecutionAction` are exported from `@lifi/sdk`.
type RouteExecutionUpdate = {
  route: Route
  action: ExecutionAction
}

type RouteSelected = {
  route: Route
  routes: Route[]
}

type TokenSearch = {
  value: string
  tokens: TokenAmount[]
}

type ChainTokenSelected = {
  chainId: ChainId
  tokenAddress: string
}

type FormFieldChanged = {
  [K in keyof DefaultValues]: {
    fieldName: K
    newValue: DefaultValues[K]
    oldValue: DefaultValues[K]
  }
}[keyof DefaultValues]

type SettingUpdated<
  K extends keyof SettingsProps = keyof SettingsProps,
> = {
  setting: K
  newValue: SettingsProps[K]
  oldValue: SettingsProps[K]
  newSettings: SettingsProps
  oldSettings: SettingsProps
}

type ChainPinned = {
  chainId: number
  pinned: boolean
}

type LowAddressActivityConfirmed = {
  address: string
  chainId: number
}
```