0
# Wallet Connection and Management
1

2
Complete wallet connection system providing components and functionality for connecting to Web3 wallets, managing connection state, switching chains, and handling wallet interactions.
3

4
## Capabilities
5

6
### Connector
7

8
High-level wrapper component that provides wallet connection functionality to its children through render props pattern. Manages connection state, modal display, and wallet interactions.
9

10
```typescript { .api }
11
/**
12
 * High-level wrapper component that provides wallet connection functionality
13
 * @param children - Child component that receives connector props  
14
 * @param modalProps - Props passed to the connection modal
15
 * @param onConnect - Callback when connection starts
16
 * @param onConnected - Callback when connection succeeds
17
 * @param onDisconnect - Callback when disconnection starts  
18
 * @param onDisconnected - Callback when disconnection completes
19
 * @param onChainSwitched - Callback when chain is switched
20
 * @param onConnectError - Callback for connection errors
21
 */
22
const Connector: React.FC<ConnectorProps>;
23

24
interface ConnectorProps {
25
  children: React.ReactNode;
26
  modalProps?: ConnectModalProps;
27
  onConnect?: () => void;
28
  onConnected?: (account?: Account) => void;
29
  onDisconnect?: () => void;
30
  onDisconnected?: () => void;
31
  onChainSwitched?: (chain?: Chain) => void;
32
  onConnectError?: (error?: Error) => void;
33
}
34
```
35

36
**Usage Example:**
37

38
```typescript
39
import { Connector } from "@ant-design/web3";
40

41
function App() {
42
  return (
43
    <Connector
44
      onConnected={(account) => {
45
        console.log('Connected account:', account);
46
      }}
47
      onChainSwitched={(chain) => {
48
        console.log('Switched to chain:', chain);
49
      }}
50
    >
51
      {(connectorProps) => (
52
        <MyCustomConnectButton {...connectorProps} />
53
      )}
54
    </Connector>
55
  );
56
}
57
```
58

59
### ConnectButton
60

61
Main connect button component providing comprehensive wallet management including connection, disconnection, chain switching, and profile modal display.
62

63
```typescript { .api }
64
/**
65
 * Main connect button component with wallet management, chain switching, and profile modal
66
 * @param chainSelect - Whether to show chain selection dropdown (default: true)
67
 * @param onConnectClick - Callback when connect is clicked
68
 * @param onDisconnectClick - Callback when disconnect is clicked
69
 * @param tooltip - Tooltip configuration
70
 * @param profileModal - Profile modal configuration  
71
 * @param quickConnect - Whether to show quick connect options
72
 * @param avatar - Avatar configuration
73
 * @param sign - Signing configuration
74
 * @param actionsMenu - Actions menu configuration
75
 * @param locale - Localization overrides
76
 */
77
const ConnectButton: React.FC<ConnectButtonProps>;
78

79
interface ConnectButtonProps extends ButtonProps, ConnectorTriggerProps {
80
  chainSelect?: boolean;
81
  onConnectClick?: (wallet?: Wallet) => void;
82
  onDisconnectClick?: () => void;
83
  tooltip?: boolean | ConnectButtonTooltipProps;
84
  profileModal?: boolean | ProfileModalProps['modalProps'];
85
  quickConnect?: boolean;
86
  avatar?: AvatarProps;
87
  sign?: SignConfig;
88
  signBtnTextRender?: (signText?: React.ReactNode, account?: Account) => React.ReactNode;
89
  onMenuItemClick?: (e: NonNullable<MenuProps['items']>[number]) => void;
90
  addressPrefix?: string | false;
91
  actionsMenu?: boolean | {
92
    items?: MenuItemType[];
93
    extraItems?: MenuItemType[];
94
  };
95
  locale?: Locale['ConnectButton'];
96
}
97

98
interface ConnectButtonTooltipProps extends TooltipProps {
99
  copyable?: boolean;
100
  title?: boolean | string | React.ReactNode;
101
  format?: AddressProps['format'];
102
}
103

104
interface AvatarProps {
105
  src?: string;
106
  size?: 'small' | 'default' | 'large' | number;
107
}
108

109
type MenuItemType = Extract<GetProp<MenuProps, 'items'>[number], { type?: 'item' }>;
110
```
111

112
**Usage Examples:**
113

114
```typescript
115
import { ConnectButton } from "@ant-design/web3";
116

117
// Basic usage
118
<ConnectButton />
119

120
// With custom callbacks
121
<ConnectButton
122
  onConnectClick={(wallet) => {
123
    console.log('Connecting to wallet:', wallet?.name);
124
  }}
125
  onDisconnectClick={() => {
126
    console.log('Disconnecting wallet');
127
  }}
128
/>
129

130
// With profile modal and tooltip
131
<ConnectButton
132
  tooltip={{ copyable: true }}
133
  profileModal={true}
134
  chainSelect={true}
135
/>
136
```
137

138
### ChainSelect
139

140
Dropdown component for selecting blockchain networks with support for chain switching and custom styling.
141

142
```typescript { .api }
143
/**
144
 * Dropdown component for selecting blockchain networks
145
 * @param chains - Available chains to select from
146
 * @param currentChain - Currently selected chain
147
 * @param onSwitchChain - Callback when chain is switched
148
 * @param buttonProps - Props for the button component
149
 */
150
const ChainSelect: React.FC<ChainSelectProps>;
151

152
interface ChainSelectProps {
153
  chains: Chain[];
154
  currentChain?: Chain;
155
  onSwitchChain?: (chain: Chain) => void;
156
  buttonProps?: ButtonProps;
157
}
158
```
159

160
**Usage Example:**
161

162
```typescript
163
import { ChainSelect } from "@ant-design/web3";
164

165
const availableChains = [
166
  { id: 1, name: "Ethereum", type: ChainType.EVM },
167
  { id: 137, name: "Polygon", type: ChainType.EVM },
168
  { id: 56, name: "BSC", type: ChainType.EVM }
169
];
170

171
<ChainSelect
172
  chains={availableChains}
173
  currentChain={availableChains[0]}
174
  onSwitchChain={(chain) => {
175
    console.log('Switching to chain:', chain.name);
176
  }}
177
/>
178
```
179

180
### ConnectModal
181

182
Modal component for wallet connection supporting multiple display modes (simple, normal, auto) with wallet grouping and connection guides.
183

184
```typescript { .api }
185
/**
186
 * Modal component for wallet connection with support for different modes
187
 * @param onWalletSelected - Wallet selection callback
188
 * @param walletList - Available wallets
189
 * @param mode - Modal display mode: 'simple' | 'normal' | 'auto'
190
 * @param guide - Guide panel configuration
191
 * @param group - Wallet grouping options
192
 * @param connecting - Connection status display
193
 * @param disabled - Whether to disable wallet connections
194
 */
195
const ConnectModal: React.FC<ConnectModalProps> & { ModalPanel: typeof ModalPanel };
196

197
interface ConnectModalProps {
198
  onWalletSelected?: (wallet: Wallet, options?: ConnectOptions) => void;
199
  walletList?: Wallet[];
200
  mode?: 'simple' | 'normal' | 'auto';
201
  guide?: DefaultGuide;
202
  group?: boolean | object;
203
  connecting?: ConnectingStatusConfig;
204
  disabled?: boolean;
205
}
206

207
interface DefaultGuide {
208
  title?: React.ReactNode;
209
  infos?: Array<{
210
    title: React.ReactNode;
211
    description: React.ReactNode;
212
    icon?: React.ReactNode;
213
  }>;
214
  moreLink?: string;
215
}
216

217
interface ConnectingStatusConfig {
218
  title?: React.ReactNode;
219
  description?: React.ReactNode;
220
}
221

222
interface ConnectOptions {
223
  connectType?: 'extension' | 'qrCode' | 'openMobile';
224
}
225
```
226

227
**Usage Examples:**
228

229
```typescript
230
import { ConnectModal } from "@ant-design/web3";
231

232
// Simple modal
233
<ConnectModal
234
  mode="simple"
235
  onWalletSelected={(wallet, options) => {
236
    console.log('Selected wallet:', wallet.name, 'with options:', options);
237
  }}
238
/>
239

240
// Normal modal with guide
241
<ConnectModal
242
  mode="normal"
243
  guide={{
244
    title: "Connect Your Wallet",
245
    infos: [
246
      {
247
        title: "Step 1",
248
        description: "Choose your preferred wallet",
249
        icon: <WalletIcon />
250
      }
251
    ]
252
  }}
253
  group={true}
254
/>
255

256
// Modal panel component
257
<ConnectModal.ModalPanel
258
  onWalletSelected={(wallet) => {
259
    console.log('Wallet selected:', wallet);
260
  }}
261
/>
262
```
263

264
## Types
265

266
### Wallet Interface
267

268
```typescript { .api }
269
interface Wallet extends WalletMetadata {
270
  _standardWallet?: any;
271
  _isMobileWallet?: boolean;
272
  hasWalletReady?: () => Promise<boolean>;
273
  hasExtensionInstalled?: () => Promise<boolean>;
274
  getQrCode?: () => Promise<{ uri: string }>;
275
  customQrCodePanel?: boolean;
276
}
277

278
type WalletMetadata = {
279
  name: string;
280
  remark: string;
281
  key?: React.Key;
282
  icon?: string | React.ReactNode;
283
  extensions?: false | WalletExtensionItem[];
284
  app?: false | { link: string };
285
  group?: string;
286
  universalProtocol?: { link: string };
287
  supportChainTypes?: ChainType[];
288
  transferQRCodeFormatter?: (params: Record<string, any>) => string;
289
  deeplink?: { urlTemplate: string };
290
};
291

292
interface WalletExtensionItem {
293
  key: string;
294
  browserIcon: string;
295
  browserName: string;
296
  link: string;
297
  description: string;
298
}
299
```
300

301
### ConnectorTriggerProps
302

303
Base props interface for components that trigger wallet connections.
304

305
```typescript { .api }
306
interface ConnectorTriggerProps {
307
  account?: Account;
308
  loading?: boolean;
309
  onConnectClick?: (wallet?: Wallet) => void;
310
  onDisconnectClick?: () => void;
311
  onSwitchChain?: (chain: Chain) => Promise<void>;
312
  availableChains?: Chain[];
313
  availableWallets?: Wallet[];
314
  chain?: Chain;
315
  balance?: Balance;
316
}
317
```
318

319
### SignConfig
320

321
Configuration interface for wallet signing functionality.
322

323
```typescript { .api }
324
interface SignConfig {
325
  signIn: (address: string) => Promise<void>;
326
  signOut?: () => Promise<void>;
327
}
328
```