> For the complete documentation index, see [llms.txt](https://docs.rango.exchange/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rango.exchange/widget-integration/events.md).

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

```typescript
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:

```typescript
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:

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

And these are related types declarations for route events:

```typescript
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:

```typescript
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:

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

And these are related types declarations for step events:

```typescript
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:

```typescript
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:

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

And these are related types declarations for wallet events:

```typescript
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:

```typescript
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:

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

And these are related types declarations for route events:

```typescript
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:

```typescript
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:

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

And these are related types declarations for route events:

```typescript
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;
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.rango.exchange/widget-integration/events.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.