⚡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 Discord.

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:

import type { Route } from '@lifi/sdk';
import type { RouteExecutionUpdate } 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.all.clear();
  }, [widgetEvents]);

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

List of events

Here is the list of all available events:

Name	Arguments Type	Description
RouteExecutionStarted	Route	The event fires when the user clicks on the Start swapping or Start bridging button.
RouteExecutionUpdated	RouteExecutionUpdate	The event fires when there is an update to the Route object during execution.
RouteExecutionCompleted	Route	The event fires when the execution is completed successfully.
RouteExecutionFailed	RouteExecutionUpdate	The event fires when the execution has failed.
RouteHighValueLoss	RouteHighValueLossUpdate	The event fires when the High Value Loss bottom sheet appears on the screen.
ContactSupport	ContactSupport	The event fires when the user clicks on the Contact support button on the Transaction Details page.
SourceChainTokenSelected	ChainTokenSelected	The event fires when the user selects the source chain and token.
DestinationChainTokenSelected	ChainTokenSelected	The event fires when the user selects the destination chain and token.
SendToWalletToggled	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.
ReviewTransactionPageEntered	Route	The event fires when the user enters the Review Transaction page by clicking on a route.
WalletConnected	WalletConnected	The event fires when the user connects the wallet via the internal wallet management UI.
WidgetExpanded	boolean	The event fires when the side panel with routes is shown to the user. Only available in wide widget variant.

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.

enum WidgetEvent {
  RouteExecutionStarted = 'routeExecutionStarted',
  RouteExecutionUpdated = 'routeExecutionUpdated',
  RouteExecutionCompleted = 'routeExecutionCompleted',
  RouteExecutionFailed = 'routeExecutionFailed',
  RouteHighValueLoss = 'routeHighValueLoss',
  ContactSupport = 'contactSupport',
  SourceChainTokenSelected = 'sourceChainTokenSelected',
  DestinationChainTokenSelected = 'destinationChainTokenSelected',
  SendToWalletToggled = 'sendToWalletToggled',
  ReviewTransactionPageEntered = 'reviewTransactionPageEntered',
  WalletConnected = 'walletConnected',
  WidgetExpanded = 'widgetExpanded',
}

type WidgetEvents = {
  routeExecutionStarted: Route;
  routeExecutionUpdated: RouteExecutionUpdate;
  routeExecutionCompleted: Route;
  routeExecutionFailed: RouteExecutionUpdate;
  routeHighValueLoss: RouteHighValueLossUpdate;
  contactSupport: ContactSupport;
  sourceChainTokenSelected: ChainTokenSelected;
  destinationChainTokenSelected: ChainTokenSelected;
  sendToWalletToggled: boolean;
  reviewTransactionPageEntered?: Route;
  walletConnected: WalletConnected;
  widgetExpanded: boolean;
};

interface ContactSupport {
  supportId?: string;
}

interface RouteHighValueLossUpdate {
  fromAmountUSD: number;
  toAmountUSD: number;
  gasCostUSD?: number;
  feeCostUSD?: number;
  valueLoss: number;
}

interface RouteExecutionUpdate {
  route: Route;
  process: Process;
}

interface ChainTokenSelected {
  chainId: ChainId;
  tokenAddress: string;
}

interface WalletConnected {
  address?: string;
  chainId?: number;
  chainType?: ChainType;
}

👛Wallet Management