> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](/documentation/features/custom-events.md).

# 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()`.

```javascript
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**

```javascript
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**

```javascript
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**

```jsx
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**

```vue
<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.

```javascript
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.

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

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