Custom Events

The widget dispatches custom DOM events at key points in the wallet connection and transaction flow

You can listen for these events to react to state changes, update your UI, or trigger your own logic — without modifying the widget's internal code.

walletConnected

Fired immediately after a wallet is successfully connected, whether via the standard modal or directConnectWallet().

document.addEventListener('walletConnected', (e) => {
  console.log(e.detail.address);    // wallet address
  console.log(e.detail.walletName); // wallet name
});

Event Detail

Property

Type

Description

address

string

The connected wallet's public address

walletName

string

Display name of the wallet (e.g. "Trust Wallet")

Usage Examples

Display connected wallet in your UI

document.addEventListener('walletConnected', (e) => {
  const { address, walletName } = e.detail;

  document.getElementById('wallet-status').textContent =
    `Connected: ${walletName} (${address.slice(0, 6)}...${address.slice(-4)})`;
});

Send wallet data to your backend

document.addEventListener('walletConnected', async (e) => {
  const { address, walletName } = e.detail;

  await fetch('/api/track-connection', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ address, walletName })
  });
});

React integration

import { useEffect, useState } from 'react';

function WalletStatus() {
  const [wallet, setWallet] = useState(null);

  useEffect(() => {
    const handler = (e) => setWallet(e.detail);
    document.addEventListener('walletConnected', handler);
    return () => document.removeEventListener('walletConnected', handler);
  }, []);

  if (!wallet) return <p>No wallet connected</p>;

  return (
    <p>
      {wallet.walletName}: {wallet.address}
    </p>
  );
}

Vue.js integration

<template>
  <p v-if="wallet">{{ wallet.walletName }}: {{ wallet.address }}</p>
  <p v-else>No wallet connected</p>
</template>

<script>
export default {
  data() {
    return { wallet: null };
  },
  mounted() {
    this._walletHandler = (e) => { this.wallet = e.detail; };
    document.addEventListener('walletConnected', this._walletHandler);
  },
  beforeUnmount() {
    document.removeEventListener('walletConnected', this._walletHandler);
  }
};
</script>

Important Notes

Always remove listeners when done

Failing to remove event listeners can cause memory leaks in single-page applications.

const handler = (e) => console.log(e.detail);

// Add
document.addEventListener('walletConnected', handler);

// Remove when no longer needed
document.removeEventListener('walletConnected', handler);

Events are fired on document

All custom events are dispatched on the document object. Listening on a specific DOM element will not work.

// ✅ Correct
document.addEventListener('walletConnected', handler);

// ❌ Incorrect
document.getElementById('widget').addEventListener('walletConnected', handler);

PreviousCustom Modal

NextShowcases

Last updated 7 months ago