useSwitchAccount ​

Hook for switching the current account.

Import ​

import { useSwitchAccount } from 'wagmi'

import { useSwitchAccount } from 'wagmi'

Usage ​

import { useSwitchAccount } from 'wagmi'

function App() {
  const { connectors, switchAccount } = useSwitchAccount()

  return (
    <div>
      {connectors.map((connector) => (
        <button key={connector.id} onClick={() => switchAccount({ connector })}>
          {connector.name}
        </button>
      ))}
    </div>
  )
}

import { useSwitchAccount } from 'wagmi'

function App() {
  const { connectors, switchAccount } = useSwitchAccount()

  return (
    <div>
      {connectors.map((connector) => (
        <button key={connector.id} onClick={() => switchAccount({ connector })}>
          {connector.name}
        </button>
      ))}
    </div>
  )
}

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

Parameters ​

import { type UseSwitchAccountParameters } from 'wagmi'

import { type UseSwitchAccountParameters } from 'wagmi'

config ​

Config | undefined

Config to use instead of retrieving from the from nearest WagmiProvider.

import { useSwitchAccount } from 'wagmi'
import { config } from './config' 

function App() {
  const result = useSwitchAccount({
    config, 
  })
}

import { useSwitchAccount } from 'wagmi'
import { config } from './config' 

function App() {
  const result = useSwitchAccount({
    config, 
  })
}

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

mutation ​

TanStack Query parameters. See the TanStack Query mutation docs for more info.

gcTime ​

number | Infinity | undefined

• The time in milliseconds that unused/inactive cache data remains in memory. When a mutation's cache becomes unused or inactive, that cache data will be garbage collected after this duration. When different cache times are specified, the longest one will be used.
• If set to Infinity, will disable garbage collection

meta ​

Record<string, unknown> | undefined

If set, stores additional information on the mutation cache entry that can be used as needed. It will be accessible wherever switchAccount is available (e.g. onError, onSuccess functions).

networkMode ​

'online' | 'always' | 'offlineFirst' | undefined

• defaults to 'online'
• see Network Mode for more information.

onError ​

((error: SwitchAccountErrorType, variables: SwitchAccountVariables, context?: context | undefined) => Promise<unknown> | unknown) | undefined

This function will fire if the mutation encounters an error and will be passed the error.

onMutate ​

((variables: SwitchAccountVariables) => Promise<context | void> | context | void) | undefined

• This function will fire before the mutation function is fired and is passed the same variables the mutation function would receive
• Useful to perform optimistic updates to a resource in hopes that the mutation succeeds
• The value returned from this function will be passed to both the onError and onSettled functions in the event of a mutation failure and can be useful for rolling back optimistic updates.

onSuccess ​

((data: SwitchAccountData, variables: SwitchAccountVariables, context?: context | undefined) => Promise<unknown> | unknown) | undefined

This function will fire when the mutation is successful and will be passed the mutation's result.

onSettled ​

((data: SwitchAccountData, error: SwitchAccountErrorType, variables: SwitchAccountVariables, context?: context | undefined) => Promise<unknown> | unknown) | undefined

This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error

queryClient ​

QueryClient

Use this to use a custom QueryClient. Otherwise, the one from the nearest context will be used.

retry ​

boolean | number | ((failureCount: number, error: SwitchAccountErrorType) => boolean) | undefined

• Defaults to 0.
• If false, failed mutations will not retry.
• If true, failed mutations will retry infinitely.
• If set to an number, e.g. 3, failed mutations will retry until the failed mutations count meets that number.

retryDelay ​

number | ((retryAttempt: number, error: SwitchAccountErrorType) => number) | undefined

• This function receives a retryAttempt integer and the actual Error and returns the delay to apply before the next attempt in milliseconds.
• A function like attempt => Math.min(attempt > 1 ? 2 ** attempt * 1000 : 1000, 30 * 1000) applies exponential backoff.
• A function like attempt => attempt * 1000 applies linear backoff.

Return Type ​

import { type UseSwitchAccountReturnType } from 'wagmi'

import { type UseSwitchAccountReturnType } from 'wagmi'

connectors ​

readonly Connector[]

Globally configured and actively connected connectors. Useful for rendering a list of available connectors to switch to.

import { useSwitchAccount } from 'wagmi'

function App() {
  const { connectors, switchAccount } = useSwitchAccount()

  return (
    <div>
      {connectors.map((connector) => (
        <button key={connector.id} onClick={() => switchAccount({ connector })}>
          {connector.name}
        </button>
      ))}
    </div>
  )
}

import { useSwitchAccount } from 'wagmi'

function App() {
  const { connectors, switchAccount } = useSwitchAccount()

  return (
    <div>
      {connectors.map((connector) => (
        <button key={connector.id} onClick={() => switchAccount({ connector })}>
          {connector.name}
        </button>
      ))}
    </div>
  )
}

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

import { http, createConfig } from 'wagmi'
import { mainnet, sepolia } from 'wagmi/chains'

export const config = createConfig({
  chains: [mainnet, sepolia],
  transports: {
    [mainnet.id]: http(),
    [sepolia.id]: http(),
  },
})

TanStack Query mutation docs

switchAccount ​

(variables: SwitchAccountVariables, { onSuccess, onSettled, onError }) => void

The mutation function you can call with variables to trigger the mutation and optionally hooks on additional callback options.

• variables ​

  SwitchAccountVariables

  The variables object to pass to the switchAccount action.

• onSuccess ​

  (data: SwitchAccountData, variables: SwitchAccountVariables, context: TContext) => void

  This function will fire when the mutation is successful and will be passed the mutation's result.

• onError ​

  (error: SwitchAccountErrorType, variables: SwitchAccountVariables, context: TContext | undefined) => void

  This function will fire if the mutation encounters an error and will be passed the error.

• onSettled ​

  (data: SwitchAccountData | undefined, error: SwitchAccountErrorType | null, variables: SwitchAccountVariables, context: TContext | undefined) => void

  • This function will fire when the mutation is either successfully fetched or encounters an error and be passed either the data or error
  • If you make multiple requests, onSuccess will fire only after the latest call you've made.

switchAccountAsync ​

(variables: SwitchAccountVariables, { onSuccess, onSettled, onError }) => Promise<SwitchAccountData>

Similar to switchAccount but returns a promise which can be awaited.

data ​

SwitchAccountData | undefined

• switchAccount return type
• Defaults to undefined
• The last successfully resolved data for the mutation.

error ​

SwitchAccountErrorType | null

The error object for the mutation, if an error was encountered.

failureCount ​

number

• The failure count for the mutation.
• Incremented every time the mutation fails.
• Reset to 0 when the mutation succeeds.

failureReason ​

SwitchAccountErrorType | null

• The failure reason for the mutation retry.
• Reset to null when the mutation succeeds.

isError / isIdle / isPending / isSuccess ​

boolean

Boolean variables derived from status.

isPaused ​

boolean

• will be true if the mutation has been paused.
• see Network Mode for more information.

reset ​

() => void

A function to clean the mutation internal state (e.g. it resets the mutation to its initial state).

status ​

'idle' | 'pending' | 'error' | 'success'

• 'idle' initial status prior to the mutation function executing.
• 'pending' if the mutation is currently executing.
• 'error' if the last mutation attempt resulted in an error.
• 'success' if the last mutation attempt was successful.

submittedAt ​

number

• The timestamp for when the mutation was submitted.
• Defaults to 0.

variables ​

SwitchAccountVariables | undefined

• The variables object passed to switchAccount.
• Defaults to undefined.

TanStack Query ​

import {
  type SwitchAccountData,
  type SwitchAccountVariables,
  type SwitchAccountMutate,
  type SwitchAccountMutateAsync,
  switchAccountMutationOptions,
} from 'wagmi/query'

import {
  type SwitchAccountData,
  type SwitchAccountVariables,
  type SwitchAccountMutate,
  type SwitchAccountMutateAsync,
  switchAccountMutationOptions,
} from 'wagmi/query'

Action ​

• switchAccount