0
# Account Management
1

2
Wallet connection, disconnection, and account switching functionality with full connector lifecycle management. This module handles the complete wallet interaction flow from initial connection through account switching and disconnection.
3

4
## Capabilities
5

6
### useAccount
7

8
Hook to get current account information including connection status, address, and active connector.
9

10
```typescript { .api }
11
/**
12
 * Hook to get current account information
13
 * @param parameters - Optional configuration parameters
14
 * @returns Current account data and connection status
15
 */
16
function useAccount<config = Config>(
17
  parameters?: UseAccountParameters<config>
18
): UseAccountReturnType<config>;
19

20
interface UseAccountParameters<config = Config> {
21
  config?: Config | config;
22
}
23

24
interface UseAccountReturnType<config = Config> {
25
  /** Primary account address */
26
  address?: Address;
27
  /** All connected addresses */
28
  addresses?: readonly Address[];
29
  /** Current chain information */
30
  chain?: Chain;
31
  /** Current chain ID */
32
  chainId?: number;
33
  /** Active connector instance */
34
  connector?: Connector;
35
  /** Connection status flags */
36
  isConnected: boolean;
37
  isConnecting: boolean;
38
  isDisconnected: boolean;
39
  isReconnecting: boolean;
40
  /** Current connection status */
41
  status: 'connecting' | 'connected' | 'disconnected' | 'reconnecting';
42
}
43
```
44

45
**Usage Example:**
46

47
```typescript
48
import { useAccount } from "wagmi";
49

50
function Profile() {
51
  const { 
52
    address, 
53
    isConnected, 
54
    isConnecting, 
55
    connector 
56
  } = useAccount();
57

58
  if (isConnecting) return <div>Connecting...</div>;
59
  if (!isConnected) return <div>Not connected</div>;
60

61
  return (
62
    <div>
63
      <p>Address: {address}</p>
64
      <p>Connected via: {connector?.name}</p>
65
    </div>
66
  );
67
}
68
```
69

70
### useConnect
71

72
Hook to connect to a wallet with support for multiple connectors and connection parameters.
73

74
```typescript { .api }
75
/**
76
 * Hook to connect to a wallet
77
 * @param parameters - Optional connection configuration
78
 * @returns Connect mutation and available connectors
79
 */
80
function useConnect<config = Config, context = unknown>(
81
  parameters?: UseConnectParameters<config, context>
82
): UseConnectReturnType<config, context>;
83

84
interface UseConnectParameters<config = Config, context = unknown> {
85
  config?: Config | config;
86
  mutation?: {
87
    onMutate?: (variables: ConnectVariables) => Promise<context> | context;
88
    onError?: (error: ConnectErrorType, variables: ConnectVariables, context?: context) => Promise<void> | void;
89
    onSuccess?: (data: ConnectData, variables: ConnectVariables, context?: context) => Promise<void> | void;
90
    onSettled?: (data?: ConnectData, error?: ConnectErrorType, variables?: ConnectVariables, context?: context) => Promise<void> | void;
91
  };
92
}
93

94
interface UseConnectReturnType<config = Config, context = unknown> {
95
  /** Available connectors */
96
  connectors: readonly Connector[];
97
  /** Connect to a specific connector */
98
  connect: (variables: ConnectVariables, options?: ConnectMutateOptions) => void;
99
  /** Async version of connect */
100
  connectAsync: (variables: ConnectVariables, options?: ConnectMutateAsyncOptions) => Promise<ConnectData>;
101
  /** Current connection data */
102
  data?: ConnectData;
103
  /** Connection error */
104
  error: ConnectErrorType | null;
105
  /** Connection status flags */
106
  isError: boolean;
107
  isIdle: boolean;
108
  isPending: boolean;
109
  isSuccess: boolean;
110
  /** Reset connection state */
111
  reset: () => void;
112
  /** Current status */
113
  status: 'error' | 'idle' | 'pending' | 'success';
114
  /** Additional variables */
115
  variables?: ConnectVariables;
116
}
117

118
interface ConnectVariables {
119
  /** Connector to connect with */
120
  connector: Connector;
121
  /** Optional chain ID to connect to */
122
  chainId?: number;
123
}
124

125
interface ConnectData {
126
  /** Connected accounts */
127
  accounts: readonly Address[];
128
  /** Connected chain ID */
129
  chainId: number;
130
}
131
```
132

133
**Usage Example:**
134

135
```typescript
136
import { useConnect } from "wagmi";
137
import { metaMask, walletConnect } from "wagmi/connectors";
138

139
function ConnectWallet() {
140
  const { connectors, connect, isPending } = useConnect();
141

142
  return (
143
    <div>
144
      {connectors.map((connector) => (
145
        <button
146
          key={connector.id}
147
          onClick={() => connect({ connector })}
148
          disabled={isPending}
149
        >
150
          {isPending ? 'Connecting...' : `Connect ${connector.name}`}
151
        </button>
152
      ))}
153
    </div>
154
  );
155
}
156
```
157

158
### useDisconnect
159

160
Hook to disconnect from the currently connected wallet.
161

162
```typescript { .api }
163
/**
164
 * Hook to disconnect from wallet
165
 * @param parameters - Optional disconnection configuration
166
 * @returns Disconnect mutation
167
 */
168
function useDisconnect<config = Config, context = unknown>(
169
  parameters?: UseDisconnectParameters<config, context>
170
): UseDisconnectReturnType<config, context>;
171

172
interface UseDisconnectParameters<config = Config, context = unknown> {
173
  config?: Config | config;
174
  mutation?: {
175
    onMutate?: (variables: DisconnectVariables) => Promise<context> | context;
176
    onError?: (error: DisconnectErrorType, variables: DisconnectVariables, context?: context) => Promise<void> | void;
177
    onSuccess?: (data: DisconnectData, variables: DisconnectVariables, context?: context) => Promise<void> | void;
178
    onSettled?: (data?: DisconnectData, error?: DisconnectErrorType, variables?: DisconnectVariables, context?: context) => Promise<void> | void;
179
  };
180
}
181

182
interface UseDisconnectReturnType<config = Config, context = unknown> {
183
  /** Disconnect from wallet */
184
  disconnect: (variables?: DisconnectVariables, options?: DisconnectMutateOptions) => void;
185
  /** Async version of disconnect */
186
  disconnectAsync: (variables?: DisconnectVariables, options?: DisconnectMutateAsyncOptions) => Promise<DisconnectData>;
187
  /** Disconnection data */
188
  data?: DisconnectData;
189
  /** Disconnection error */
190
  error: DisconnectErrorType | null;
191
  /** Disconnection status flags */
192
  isError: boolean;
193
  isIdle: boolean;
194
  isPending: boolean;
195
  isSuccess: boolean;
196
  /** Reset disconnection state */
197
  reset: () => void;
198
  /** Current status */
199
  status: 'error' | 'idle' | 'pending' | 'success';
200
  /** Additional variables */
201
  variables?: DisconnectVariables;
202
}
203

204
interface DisconnectVariables {
205
  /** Optional connector to disconnect specifically */
206
  connector?: Connector;
207
}
208

209
interface DisconnectData {
210
  /** Whether disconnection was successful */
211
  success: boolean;
212
}
213
```
214

215
### useConnectors
216

217
Hook to get all available connectors configured in the wagmi instance.
218

219
```typescript { .api }
220
/**
221
 * Hook to get available connectors
222
 * @param parameters - Optional configuration parameters
223
 * @returns Array of available connectors
224
 */
225
function useConnectors<config = Config>(
226
  parameters?: UseConnectorsParameters<config>
227
): UseConnectorsReturnType;
228

229
interface UseConnectorsParameters<config = Config> {
230
  config?: Config | config;
231
}
232

233
interface UseConnectorsReturnType {
234
  0: readonly Connector[];
235
}
236
```
237

238
### useConnections
239

240
Hook to get all current connections across multiple connectors.
241

242
```typescript { .api }
243
/**
244
 * Hook to get current connections
245
 * @param parameters - Optional configuration parameters
246
 * @returns Array of active connections
247
 */
248
function useConnections<config = Config>(
249
  parameters?: UseConnectionsParameters<config>
250
): UseConnectionsReturnType<config>;
251

252
interface UseConnectionsParameters<config = Config> {
253
  config?: Config | config;
254
}
255

256
interface UseConnectionsReturnType<config = Config> {
257
  0: readonly Connection[];
258
}
259

260
interface Connection {
261
  /** Connected accounts */
262
  accounts: readonly Address[];
263
  /** Chain ID */
264
  chainId: number;
265
  /** Connector instance */
266
  connector: Connector;
267
}
268
```
269

270
### useReconnect
271

272
Hook to reconnect to previously connected wallets on app initialization.
273

274
```typescript { .api }
275
/**
276
 * Hook to reconnect to previously connected wallets
277
 * @param parameters - Optional reconnection configuration
278
 * @returns Reconnect mutation
279
 */
280
function useReconnect<config = Config, context = unknown>(
281
  parameters?: UseReconnectParameters<config, context>
282
): UseReconnectReturnType<config, context>;
283

284
interface UseReconnectParameters<config = Config, context = unknown> {
285
  config?: Config | config;
286
  mutation?: {
287
    onMutate?: (variables: ReconnectVariables) => Promise<context> | context;
288
    onError?: (error: ReconnectErrorType, variables: ReconnectVariables, context?: context) => Promise<void> | void;
289
    onSuccess?: (data: ReconnectData, variables: ReconnectVariables, context?: context) => Promise<void> | void;
290
    onSettled?: (data?: ReconnectData, error?: ReconnectErrorType, variables?: ReconnectVariables, context?: context) => Promise<void> | void;
291
  };
292
}
293

294
interface UseReconnectReturnType<config = Config, context = unknown> {
295
  /** Reconnect to wallets */
296
  reconnect: (variables?: ReconnectVariables, options?: ReconnectMutateOptions) => void;
297
  /** Async version of reconnect */
298
  reconnectAsync: (variables?: ReconnectVariables, options?: ReconnectMutateAsyncOptions) => Promise<ReconnectData>;
299
  /** Reconnection data */
300
  data?: ReconnectData;
301
  /** Reconnection error */
302
  error: ReconnectErrorType | null;
303
  /** Reconnection status flags */
304
  isError: boolean;
305
  isIdle: boolean;
306
  isPending: boolean;
307
  isSuccess: boolean;
308
  /** Reset reconnection state */
309
  reset: () => void;
310
  /** Current status */
311
  status: 'error' | 'idle' | 'pending' | 'success';
312
  /** Additional variables */
313
  variables?: ReconnectVariables;
314
}
315

316
interface ReconnectVariables {
317
  /** Optional specific connectors to reconnect */
318
  connectors?: Connector[];
319
}
320

321
interface ReconnectData {
322
  /** Successfully reconnected connections */
323
  connections: Connection[];
324
}
325
```
326

327
### useSwitchChain
328

329
Hook to switch between different blockchain networks.
330

331
```typescript { .api }
332
/**
333
 * Hook to switch between chains
334
 * @param parameters - Optional switch chain configuration
335
 * @returns Switch chain mutation
336
 */
337
function useSwitchChain<config = Config, context = unknown>(
338
  parameters?: UseSwitchChainParameters<config, context>
339
): UseSwitchChainReturnType<config, context>;
340

341
interface UseSwitchChainParameters<config = Config, context = unknown> {
342
  config?: Config | config;
343
  mutation?: {
344
    onMutate?: (variables: SwitchChainVariables) => Promise<context> | context;
345
    onError?: (error: SwitchChainErrorType, variables: SwitchChainVariables, context?: context) => Promise<void> | void;
346
    onSuccess?: (data: SwitchChainData, variables: SwitchChainVariables, context?: context) => Promise<void> | void;
347
    onSettled?: (data?: SwitchChainData, error?: SwitchChainErrorType, variables?: SwitchChainVariables, context?: context) => Promise<void> | void;
348
  };
349
}
350

351
interface UseSwitchChainReturnType<config = Config, context = unknown> {
352
  /** Available chains to switch to */
353
  chains: readonly Chain[];
354
  /** Switch to a specific chain */
355
  switchChain: (variables: SwitchChainVariables, options?: SwitchChainMutateOptions) => void;
356
  /** Async version of switch chain */
357
  switchChainAsync: (variables: SwitchChainVariables, options?: SwitchChainMutateAsyncOptions) => Promise<SwitchChainData>;
358
  /** Switch chain data */
359
  data?: SwitchChainData;
360
  /** Switch chain error */
361
  error: SwitchChainErrorType | null;
362
  /** Switch chain status flags */
363
  isError: boolean;
364
  isIdle: boolean;
365
  isPending: boolean;
366
  isSuccess: boolean;
367
  /** Reset switch chain state */
368
  reset: () => void;
369
  /** Current status */
370
  status: 'error' | 'idle' | 'pending' | 'success';
371
  /** Additional variables */
372
  variables?: SwitchChainVariables;
373
}
374

375
interface SwitchChainVariables {
376
  /** Chain ID to switch to */
377
  chainId: number;
378
  /** Optional specific connector */
379
  connector?: Connector;
380
}
381

382
interface SwitchChainData {
383
  /** Switched chain ID */
384
  chainId: number;
385
}
386
```
387

388
### useSwitchAccount
389

390
Hook to switch between different accounts within the same wallet.
391

392
```typescript { .api }
393
/**
394
 * Hook to switch between accounts
395
 * @param parameters - Optional switch account configuration
396
 * @returns Switch account mutation
397
 */
398
function useSwitchAccount<config = Config, context = unknown>(
399
  parameters?: UseSwitchAccountParameters<config, context>
400
): UseSwitchAccountReturnType<config, context>;
401

402
interface UseSwitchAccountParameters<config = Config, context = unknown> {
403
  config?: Config | config;
404
  mutation?: {
405
    onMutate?: (variables: SwitchAccountVariables) => Promise<context> | context;
406
    onError?: (error: SwitchAccountErrorType, variables: SwitchAccountVariables, context?: context) => Promise<void> | void;
407
    onSuccess?: (data: SwitchAccountData, variables: SwitchAccountVariables, context?: context) => Promise<void> | void;
408
    onSettled?: (data?: SwitchAccountData, error?: SwitchAccountErrorType, variables?: SwitchAccountVariables, context?: context) => Promise<void> | void;
409
  };
410
}
411

412
interface UseSwitchAccountReturnType<config = Config, context = unknown> {
413
  /** Switch to a specific account */
414
  switchAccount: (variables: SwitchAccountVariables, options?: SwitchAccountMutateOptions) => void;
415
  /** Async version of switch account */
416
  switchAccountAsync: (variables: SwitchAccountVariables, options?: SwitchAccountMutateAsyncOptions) => Promise<SwitchAccountData>;
417
  /** Switch account data */
418
  data?: SwitchAccountData;
419
  /** Switch account error */
420
  error: SwitchAccountErrorType | null;
421
  /** Switch account status flags */
422
  isError: boolean;
423
  isIdle: boolean;
424
  isPending: boolean;
425
  isSuccess: boolean;
426
  /** Reset switch account state */
427
  reset: () => void;
428
  /** Current status */
429
  status: 'error' | 'idle' | 'pending' | 'success';
430
  /** Additional variables */
431
  variables?: SwitchAccountVariables;
432
}
433

434
interface SwitchAccountVariables {
435
  /** Account address to switch to */
436
  account: Address;
437
  /** Optional specific connector */
438
  connector?: Connector;
439
}
440

441
interface SwitchAccountData {
442
  /** Switched account address */
443
  account: Address;
444
}
445
```
446

447
### useAccountEffect
448

449
Hook to react to account changes with custom effect callbacks.
450

451
```typescript { .api }
452
/**
453
 * Hook to react to account changes
454
 * @param parameters - Effect configuration with callbacks
455
 * @returns void
456
 */
457
function useAccountEffect(parameters: UseAccountEffectParameters): void;
458

459
interface UseAccountEffectParameters {
460
  /** Called when account connects */
461
  onConnect?: (data: {
462
    address: Address;
463
    addresses: readonly Address[];
464
    chainId: number;
465
    connector: Connector;
466
    isReconnected: boolean;
467
  }) => void;
468
  /** Called when account disconnects */
469
  onDisconnect?: () => void;
470
}
471
```
472

473
**Usage Example:**
474

475
```typescript
476
import { useAccountEffect } from "wagmi";
477

478
function App() {
479
  useAccountEffect({
480
    onConnect(data) {
481
      console.log('Connected!', data.address);
482
    },
483
    onDisconnect() {
484
      console.log('Disconnected!');
485
    },
486
  });
487

488
  return <div>My App</div>;
489
}
490
```
491

492
## Common Types
493

494
```typescript { .api }
495
type Address = `0x${string}`;
496

497
interface Chain {
498
  id: number;
499
  name: string;
500
  network: string;
501
  nativeCurrency: {
502
    name: string;
503
    symbol: string;
504
    decimals: number;
505
  };
506
  rpcUrls: {
507
    default: { http: readonly string[] };
508
    public: { http: readonly string[] };
509
  };
510
  blockExplorers?: {
511
    default: { name: string; url: string };
512
  };
513
  contracts?: {
514
    ensRegistry?: { address: Address };
515
    multicall3?: { address: Address };
516
  };
517
}
518

519
interface Connector {
520
  id: string;
521
  name: string;
522
  type: string;
523
  icon?: string;
524
}
525
```