🎵Events

Subscribe to Rango Widget Events

Various types of events are triggered as a result of different scenarios and states. You can subscribe to these events to implement your custom logic in your dApp. The events emitted from the widget can be categorized into four distinct groups, each of which is explained below.

There are different events that will be triggered:

export type Events = {
  [WidgetEvents.RouteEvent]: RouteEventData;
  [WidgetEvents.StepEvent]: StepEventData;
  [WidgetEvents.QuoteEvent]: QuoteEventData;
  [WidgetEvents.WalletEvent]: WalletEventData;
  [WidgetEvents.UiEvent]: UiEventData;
};

Route Events

Once a user executes a route within Rango Widget, various events will be triggered depending on the different states of the route. You can subscribe to these events to implement your custom logic related to executing routes. For instance, you can display a personalized notification whenever a route succeeds or fails.

Here is a sample code:

import { useEffect } from "react";
import {
  Widget,
  widgetEventEmitter,
  WidgetEvents,
} from "@rango-dev/widget-embedded";

export function Component() {
  useEffect(() => {
    widgetEventEmitter.on(WidgetEvents.RouteEvent, (routeEvent) => {
      const { event, route } = routeEvent;
      // your custom logic goes here
    });
    return () => widgetEventEmitter.off(WidgetEvents.RouteEvent);
  }, [widgetEventEmitter]);
}

Here is a sample usage:

widgetEvents.on(WidgetEvents.RouteEvent, ({ route: Route; event: RouteEvent }) => {})

And these are related types declarations for route events:

type RouteEvent =
  | Event<RouteEventType.STARTED>
  | Event<RouteEventType.FAILED, FailedRouteEventPayload>
  | Event<RouteEventType.SUCCEEDED, SucceededRouteEventPayload>;

type RouteEventData = { route: Route; event: RouteEvent };

Step Events

Once a user executes a swap within Rango Widget, various events will be triggered depending on the different states of each step transactions. You can subscribe to these events to implement your custom logic related to executing steps of each transaction. For instance, you can display a personalized notification whenever a step of a transaction succeeds or fails.

Here is a sample code:

import { useEffect } from "react";
import {
  Widget,
  widgetEventEmitter,
  WidgetEvents,
} from "@rango-dev/widget-embedded";

export function Component() {
  useEffect(() => {
    widgetEventEmitter.on(WidgetEvents.StepEvent, (stepEvent) => {
      const { event, route, step } = stepEvent;
      // your custom logic goes here
    });
    return () => widgetEventEmitter.off(WidgetEvents.StepEvent);
  }, [widgetEventEmitter]);
}

Here is a sample usage:

widgetEvents.on(WidgetEvents.StepEvent, ({ route: Route; step: Step; event: StepEvent }) => {})

And these are related types declarations for step events:

type StepStartedEvent = Event<StepEventType.STARTED>;
type StepSucceededEvent = Event<
  StepEventType.SUCCEEDED,
  SucceededStepEventPayload
>;
type StepFailedEvent = Event<StepEventType.FAILED, FailedStepEventPayload>;
type StepTxExecutionUpdatedEvent = Event<
  StepEventType.TX_EXECUTION,
  StepExecutionEventPayload
>;
type StepTxExecutionBlockedEvent = Event<
  StepEventType.TX_EXECUTION_BLOCKED,
  StepBlockedEventPayload
>;
type StepCheckStatusEvent = Event<StepEventType.CHECK_STATUS>;
type StepApprovalTxSucceededEvent = Event<StepEventType.APPROVAL_TX_SUCCEEDED>;
type StepOutputRevealedEvent = Event<
  StepEventType.OUTPUT_REVEALED,
  OutputRevealedEventPayload
>;

type StepEvent =
  | StepStartedEvent
  | StepSucceededEvent
  | StepFailedEvent
  | StepTxExecutionUpdatedEvent
  | StepTxExecutionBlockedEvent
  | StepCheckStatusEvent
  | StepApprovalTxSucceededEvent
  | StepOutputRevealedEvent;

type StepEventData = { route: Route; step: Step; event: StepEvent };

Wallet Events

Once a user connects or disconnects a wallet within Rango Widget, various events will be triggered depending on the different states of the wallet. You can subscribe to these events to implement your custom logic related connecting or disconnecting wallets. For instance, you can display a personalized notification whenever a wallet connects or disconnects.

Here is a sample code:

import { useEffect } from "react";
import {
  Widget,
  widgetEventEmitter,
  WidgetEvents,
} from "@rango-dev/widget-embedded";

export function Component() {
  useEffect(() => {
    widgetEventEmitter.on(WidgetEvents.WalletEvent, (walletEvent) => {
      const { type, payload } = walletEvent;
      // your custom logic goes here
    });
    return () => widgetEventEmitter.off(WidgetEvents.WalletEvent);
  }, [widgetEventEmitter]);
}

Here is a sample usage:

widgetEvents.on(WidgetEvents.WalletEvent, (walletEvent: WalletEventData) => {});

And these are related types declarations for wallet events:

enum WalletEventTypes {
  CONNECT = "connect",
  DISCONNECT = "disconnect",
}

type WalletEventData =
  | EventData<WalletEventTypes.CONNECT, ConnectWalletEventPayload>
  | EventData<WalletEventTypes.DISCONNECT, DisconnectWalletEventPayload>;

type ConnectWalletEventPayload = {
  walletType: string;
  accounts: Account[];
};

type DisconnectWalletEventPayload = {
  walletType: string;
};

Quote Events

Once inputs or outputs for a quote gets updated within Rango Widget, various events will be triggered to demonstrate the changes in inputs and output. You can subscribe to these events to implement your custom logic related to updating inputs and outputs. For instance, you can update the ui of your website if a certain blockchain or token is selected in inputs.

Here is a sample code:

import { useEffect } from "react";
import {
  Widget,
  widgetEventEmitter,
  WidgetEvents,
} from "@rango-dev/widget-embedded";

export function Component() {
  useEffect(() => {
    widgetEventEmitter.on(WidgetEvents.QuoteEvent, (quoteEvent) => {
      const { type, payload } = quoteEvent;
      // your custom logic goes here
    });
    return () => widgetEventEmitter.off(WidgetEvents.QuoteEvent);
  }, [widgetEventEmitter]);
}

Here is a sample usage:

widgetEvents.on(WidgetEvents.QuoteEvent, (quoteEvent: QuoteEventData) => {});

And these are related types declarations for route events:

enum QuoteEventTypes {
  QUOTE_INPUT_UPDATE = "quoteInputUpdate",
  QUOTE_OUTPUT_UPDATE = "quoteOutputUpdate",
}

type QuoteEventData =
  | EventData<QuoteEventTypes.QUOTE_INPUT_UPDATE, QuoteInputUpdateEventPayload>
  | EventData<QuoteEventTypes.QUOTE_OUTPUT_UPDATE, QuoteUpdateEventPayload>;

type QuoteInputUpdateEventPayload = {
  fromBlockchain?: string;
  toBlockchain?: string;
  fromToken?: { symbol: string; name: string | null; address: string | null };
  toToken?: { symbol: string; name: string | null; address: string | null };
  requestAmount?: string;
};

type QuoteUpdateEventPayload = Pick<
  SelectedQuote,
  "requestAmount" | "swaps" | "outputAmount" | "resultType" | "tags"
> | null;

UI Events

Once a user does some certain actions on the widget UI, various events will be triggered depending on the action of user. You can subscribe to these events to implement your custom logic related to actions of users. For instance, you can display a personalized wallet connect modal when user clicks on "Connect Wallet" button in the widget.

Note: Currently, the only event triggered from UI is click on "Connect Wallet" button.

Here is a sample code:

import { useEffect } from "react";
import {
  Widget,
  widgetEventEmitter,
  WidgetEvents,
} from "@rango-dev/widget-embedded";

export function Component() {
  useEffect(() => {
    widgetEventEmitter.on(WidgetEvents.UiEvent, (uiEvent) => {
      const { type, payload } = uiEvent;
      // your custom logic goes here
    });
    return () => widgetEventEmitter.off(WidgetEvents.UiEvent);
  }, [widgetEventEmitter]);
}

Here is a sample usage:

widgetEvents.on(WidgetEvents.UiEvent, (uiEvent: UiEventData) => {});

And these are related types declarations for route events:

type PreventableEventPayload<
  T extends Record<string, unknown> = Record<string, unknown>
> = {
  preventDefault: () => void;
} & T;
type ClickConnectWalletPayload = PreventableEventPayload;
enum UiEventTypes {
  CLICK_CONNECT_WALLET = "clickConnectWallet",
}

type UiEventData = EventData<UiEventTypes, ClickConnectWalletPayload>;
type ClickConnectWalletPayload = PreventableEventPayload;
type PreventableEventPayload<
  T extends Record<string, unknown> = Record<string, unknown>
> = {
  preventDefault: () => void;
} & T;