Powered by

A design system from Family

API Reference

This page describes the APIs for ConnectKit which you can reference during development.


Components and Hooks

Below is a list of the React.js components and Hooks we provide as part of the ConnectKit library:

Component / HookDescription
<ConnectKitProvider />Provides state and data to various ConnectKit components. Wrap ConnectKitProvider around your React.js app.
<ConnectKitButton />The ConnectKit button. Place this component where you’d like the Connect Wallet button to appear.
<ConnectKitButton.Custom />Design your own Connect button. Various wallet connection states are provided through render props.
<Avatar />Change the avatar used in ConnectKit to more closely match the look and feel of your app.
<ChainIcon />To help with consistency, you can access ConnectKit's chain icons from within your app.
useModal()Programmatically control some aspects of the modal.
useSIWE()Programmatically control some aspects of SIWE.
useChains()Access the configured chains via this convenient Hook.

ConnectKitProvider

Wrap <ConnectKitProvider> around your React.js app to provide state and data to various ConnectKit components.

theme

Sets which theme ConnectKit should use. Below is a table of values for the theme property.

Theme PropDescriptionLight/Dark Mode Support
defaultDefault theme
web95Web95 theme
retroRetro theme
softSoft theme
midnightMidnight theme
minimalMinimal theme
roundedRounded theme
nouns Nouns theme

mode

Sets which dark/light mode configuration ConnectKit should use. Below is a table of values for the mode property.

Mode PropDescription
autoEither dark or light that matches the user's system color scheme
darkDark mode
lightLight mode

customTheme

Configure individual styles for ConnectKit, overriding styles from the selected theme. Below is a table of values for the customTheme property.

Overriding theme variables isn't a stable feature yet and could change in future versions of ConnectKit. We suggest only customizing the theme if you're confident you can migrate any changes when upgrading.

Connect Wallet Button variables

Primary Button variables

Secondary Button variables

Tertiary Button variables

Modal variables

Text variables

Miscellaneous variables

options

Configuration options you can toggle on/off. Below is a list of options and their default values that are available for the options property.

avoidLayoutShift
boolean
Default is true

Avoids layout shift when the ConnectKit modal is open by adding padding to the<body>. Alternatively, set this to false and create your own solution using the css variable --ck-scrollbar-width

bufferPolyfill
boolean
Default is true

Some bundlers require a Buffer polyfill for WalletConnect. We check and implement this by default, but if you need to disable our implementation then you can set this option to false.

customAvatar
React.ReactNode

Change the avatar used in ConnectKit to more closely match the look and feel of your app. To learn more, visit the custom avatar docs.

disableSiweRedirect
boolean

Disable the redirect to SIWE page when the user connects to a wallet.

disclaimer
ReactNode | string
Default is null

Provide a disclaimer for things like terms and conditions that will be displayed to users in the ConenctKit modal when they're not yet connected.

embedGoogleFonts
boolean
Default is false

Automatically embeds Google Font of the current theme.

enforceSupportedChains
boolean
Default is true

By default, ConnectKit will only allow users to connect to chains that are supported by your app. Set this to false to allow users to connect to any chain.

ethereumOnboardingUrl
string
Default is https://ethereum.org/en/wallets/

Link to a resource for learning more about Ethereum.

hideBalance
boolean

Hide balance in the profile view.

hideNoWalletCTA
boolean

Hide the "I don't have a wallet" call to action in the ConnectKit modal

hideQuestionMarkCTA
boolean

Hide the question mark in top-left of the ConnectKit modal that leads to the "About Wallets" page

hideRecentBadge
boolean
Default is false

Hide the "Recent" badge that appears on the most recently connected wallet connector.

hideTooltips
boolean

Hide any tooltips that would normally appear

initialChainId
number
Default is the first chain in your wagmi config

Target a specific chain to request connection to. By default ConnectKit will autotarget the first chain defined in your WagmiProvider's config'. Set this to 0 to remove chain targetting.

language
'en-US' | 'es-ES' | 'fr-FR' | 'ja-JP' | 'pt-BR' | 'zh-CN'

Customize the language used in ConnectKit to better suit your audience.

overlayBlur
number

Accepts a numerical value to control the degree of blur applied to the overlay. Alternatively you can use the theme variable --ck-overlay-backdrop-filter to achieve the same effect.

showAvatar
boolean
Default is true

Display the avatar visual in the connect button when a wallet is connected.

showBalance
boolean
Default is false

Display the connected wallet's balance in the connect button when the wallet is connected.

truncateLongENSAddress
boolean
Default is true

Truncates long ENS addresses in the connect button with ellipsis.

walletConnectCTA
'modal' | 'link' | 'both'
Default is 'modal'

When viewing the WalletConnect QR code, we display a button to open the official WalletConnect modal. This allows users to access more niche connectors if needed.
Use link to display a button to copy the WalletConnect URI. To show both options, use both.

walletConnectName
string
Default is 'Other Wallets'

By default, the WalletConnect option is named "Other Wallets". Use this option to change the name to, e.g., "WalletConnect" by providing a string.

walletOnboardingUrl
string
Default is https://ethereum.org/en/wallets/find-wallet/

Link to a resource for learning more about Wallets.

onConnect

Callback function that is called when a wallet is connected.

The onConnect callback function is called with the following arguments:

ArgumentTypeDescription
addressstringThe connected wallet address.
connectorIdstringThe ID of the wallet connector that was used to connect the wallet.

onDisconnect

Callback function that is called when a wallet is disconnected.

ConnectKitButton

Place this component where you’d like the Connect Wallet button to appear.

label
string
Default is "Connect Wallet"

Customize the connect button text/label.

showBalance
boolean
Default is false

Show/hide wallet balance when connected.

showAvatar
boolean
Default is true

Show/hide ENS/wallet avatar when connected.

ConnectKitButton.Custom

Design your own Connect button. Various wallet connection states are provided through render props.

Render Props

The custom ConnectKit button has various render props to make building a custom button easier. Below is a table of which render props are available.

isConnected
boolean

Whether or not a wallet is connected.

isConnecting
boolean

If ConnectKit is currently connecting.

show
function

Function to show the modal. In the example above we bind this to onClick for the custom button.

hide
boolean

Function to hide the modal. Mainly if you need to programmatically hide the modal.

address
string

The address of the connected wallet.

truncatedAddress
string
Default is true

A truncated version of the connected wallet address.

ensName
string

ENS name if the connected wallet address has one. Otherwise empty string.

chain
Chain

The chain the connected wallet is connected to.

Hooks


useModal

A convenience Hook to show/dismiss the modal. Must be used within a <ConnectKitProvider>.

open
boolean

Whether or not the modal is open.

setOpen
(boolean) => void

Programmatically show/dismiss the modal.

openAbout
() => void
More info

Open the modal on the About page.

openOnboarding
() => void
More info

Open the modal on the Onboarding page.

openProfile
() => void
More info

Open the modal on the Profile page.

openSwitchNetworks
() => void
More info

Open the modal on the Switch Network prompt.

openSIWE
(triggerSIWE?: boolean) => void
More info

Open the modal on the Sign In With Ethereum page. If `triggerSIWE` is set to `true` the signing request will also be prompted.

onConnect
(address: string, connectorId: string) => void

Callback function that is called when a wallet is connected.

onDisconnect
() => void

Callback function that is called when a wallet is disconnected.


useSIWE

A convenience Hook to access SIWE state. Must be used with Sign In With Ethereum.

isSignedIn
boolean

Whether or not the wallet has signed in.

data
SIWESession

Returned data when a wallet has signed in.

data properties
address
string

Wallet address.

chainId
number

Connected Chain ID.

error
Error

Error thrown if there was an error signing the message.

isRejected
boolean

If the user has rejected the signing message.

isError
boolean

If there was an error signing the message.

isLoading
boolean

If the app is waiting for the user to sign the message.

isSuccess
boolean

If the user has successfully signed in.

isReady
boolean

If the app is ready for the user to sign in.

signIn
() => Promise<boolean>

Prompt the user to sign in.

signOut
() => Promise<boolean>

Sign out the user.

reset
() => void

Reset the hook to a fresh state.


useChains

You can conveniently access your dApps configured chains via the useChains Hook. This works well with the ChainIcon component.

import { useChains, ChainIcon } from "connectkit";
const MyComponent = () => {
const chains = useChains();
return (
<>
<p>This dApp is supported on the following chains:</p>
{chains.map((chain) => (
<div key={chain.id}>
<ChainIcon id={chain.id} />
<span>{chain.name}</span>
</div>
))}
</>
);
};

Additional Components

To help support easily development we export a few components that we believe some developers might find useful.

Avatar

To help with consistency, you can access the ConnectKit <Avatar> component from within your app. You can use this component to display the user’s ENS avatar outside ConnectKit in, e.g., a profile header

If you have set up a custom avatar then this avatar component will return your custom version instead.

import { Avatar } from "connectkit";
<Avatar name="vitalik.eth" />
<Avatar name="vitalik.eth" size={64} radius={10} />
<Avatar name="vitalik.eth" size={32} radius={0} />
<Avatar address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" size={16} />
<Avatar address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" size={8} />

Below are the various props that can be passed to the Avatar component.

address
string

Wallet address

name
string

ENS name

size
number
Default is 96

Size in pixels

radius
number
Default is fully rounded

Radius in pixels

Chain Icon

To help with consistency, you can access ConnectKit's <ChainIcon> component from within your app.

Chain NameChain IDChain IconUnsupported
null
EthereumEthereum
GoerliGoerli
OP MainnetOP Mainnet
Flare MainnetFlare Mainnet
CostonCoston
Songbird MainnetSongbird Mainnet
Cronos MainnetCronos Mainnet
Rootstock MainnetRootstock Mainnet
TelosTelos
TelosTelos
LUKSOLUKSO
XinFin NetworkXinFin Network
Apothem NetworkApothem Network
BNB Smart ChainBNB Smart Chain
Syscoin MainnetSyscoin Mainnet
Ethereum ClassicEthereum Classic
OKCOKC
Conflux eSpace TestnetConflux eSpace Testnet
MeterMeter
Meter TestnetMeter Testnet
Binance Smart Chain TestnetBinance Smart Chain Testnet
GnosisGnosis
ShibariumShibarium
Coston2Coston2
FuseFuse
Fuse SparknetFuse Sparknet
PolygonPolygon
ShimmerShimmer
Manta Pacific MainnetManta Pacific Mainnet
BitTorrentBitTorrent
opBNBopBNB
Nexilix Smart ChainNexilix Smart Chain
PlingaPlinga
OasysOasys
FantomFantom
KromaKroma
zkSync Era TestnetzkSync Era Testnet
Boba NetworkBoba Network
zkSync Sepolia TestnetzkSync Sepolia Testnet
Filecoin MainnetFilecoin Mainnet
KCC MainnetKCC Mainnet
zkSync ErazkSync Era
Cronos TestnetCronos Testnet
PulseChainPulseChain
Optimism GoerliOptimism Goerli
PGNPGN
Rollux MainnetRollux Mainnet
MetaChain MainnetMetaChain Mainnet
AstarAstar
Mandala TC9Mandala TC9
Metis GoerliMetis Goerli
KaruraKarura
AcalaAcala
Taraxa MainnetTaraxa Mainnet
Taraxa TestnetTaraxa Testnet
WanchainWanchain
Mode TestnetMode Testnet
PulseChain V4PulseChain V4
5ireChain Thunder Testnet5ireChain Thunder Testnet
Wanchain TestnetWanchain Testnet
Zora Goerli TestnetZora Goerli Testnet
Klaytn Baobab TestnetKlaytn Baobab Testnet
Ekta TestnetEkta Testnet
BitTorrent Chain TestnetBitTorrent Chain Testnet
Conflux eSpaceConflux eSpace
Bronos TestnetBronos Testnet
BronosBronos
Shimmer TestnetShimmer Testnet
MetisMetis
Polygon zkEVMPolygon zkEVM
WEMIXWEMIX
WEMIX TestnetWEMIX Testnet
Core DaoCore Dao
DeFiChain EVM MainnetDeFiChain EVM Mainnet
DeFiChain EVM TestnetDeFiChain EVM Testnet
Moonbeam Development NodeMoonbeam Development Node
MoonbeamMoonbeam
MoonriverMoonriver
Moonbase AlphaMoonbase Alpha
LocalhostLocalhost
Polygon zkEVM TestnetPolygon zkEVM Testnet
TenetTenet
Horizen Gobi TestnetHorizen Gobi Testnet
LightLink PhoenixLightLink Phoenix
LightLink Pegasus TestnetLightLink Pegasus Testnet
EktaEkta
DogechainDogechain
RoninRonin
Edgeware EdgeEVM MainnetEdgeware EdgeEVM Mainnet
Saigon TestnetSaigon Testnet
Beresheet BereEVM TestnetBeresheet BereEVM Testnet
Kava EVM TestnetKava EVM Testnet
Kava EVMKava EVM
Kroma SepoliaKroma Sepolia
Filecoin HyperspaceFilecoin Hyperspace
CrossbellCrossbell
Fantom TestnetFantom Testnet
Oasis TestnetOasis Testnet
NexiNexi
IoTeXIoTeX
IoTeX TestnetIoTeX Testnet
MEVerse Chain TestnetMEVerse Chain Testnet
BlackFort Exchange Network TestnetBlackFort Exchange Network Testnet
BlackFort Exchange NetworkBlackFort Exchange Network
MantleMantle
Mantle TestnetMantle Testnet
BahamutBahamut
opBNB TestnetopBNB Testnet
Syscoin Tanenbaum TestnetSyscoin Tanenbaum Testnet
ZetaChain Athens TestnetZetaChain Athens Testnet
MEVerse Chain MainnetMEVerse Chain Mainnet
CantoCanto
Shardeum SphinxShardeum Sphinx
KlaytnKlaytn
BaseBase
JIBCHAIN L1JIBCHAIN L1
Evmos TestnetEvmos Testnet
EvmosEvmos
OORT MainnetDevOORT MainnetDev
Gnosis ChiadoGnosis Chiado
HAQQ MainnetHAQQ Mainnet
Fibo ChainFibo Chain
EOS EVM TestnetEOS EVM Testnet
HoleskyHolesky
EOS EVMEOS EVM
Oasis SapphireOasis Sapphire
Oasis Sapphire TestnetOasis Sapphire Testnet
FoundryFoundry
HardhatHardhat
ZilliqaZilliqa
Zilliqa TestnetZilliqa Testnet
Q MainnetQ Mainnet
Q TestnetQ Testnet
Arbitrum OneArbitrum One
Arbitrum NovaArbitrum Nova
CeloCelo
ZKFair MainnetZKFair Mainnet
Avalanche FujiAvalanche Fuji
AvalancheAvalanche
ZKFair TestnetZKFair Testnet
AlfajoresAlfajores
DFK ChainDFK Chain
HAQQ Testedge 2HAQQ Testedge 2
Rollux TestnetRollux Testnet
PGN PGN
Linea Goerli TestnetLinea Goerli Testnet
Linea MainnetLinea Mainnet
Fantom Sonic Open TestnetFantom Sonic Open Testnet
Polygon MumbaiPolygon Mumbai
Berachain ArtioBerachain Artio
Base GoerliBase Goerli
Base SepoliaBase Sepolia
Chiliz Spicy TestnetChiliz Spicy Testnet
Chiliz ChainChiliz Chain
VechainVechain
Taiko (Alpha-3 Testnet)Taiko (Alpha-3 Testnet)
Taiko Jolnir (Alpha-5 Testnet)Taiko Jolnir (Alpha-5 Testnet)
Taiko Katla (Alpha-6 Testnet)Taiko Katla (Alpha-6 Testnet)
Filecoin CalibrationFilecoin Calibration
Arbitrum GoerliArbitrum Goerli
Arbitrum SepoliaArbitrum Sepolia
Scroll SepoliaScroll Sepolia
ScrollScroll
Scroll TestnetScroll Testnet
Bear Network Chain MainnetBear Network Chain Mainnet
Bear Network Chain TestnetBear Network Chain Testnet
Astar zkEVM Testnet zKatanaAstar zkEVM Testnet zKatana
ZhejiangZhejiang
Manta Pacific TestnetManta Pacific Testnet
ZoraZora
SepoliaSepolia
Optimism SepoliaOptimism Sepolia
Blast SepoliaBlast Sepolia
Neon EVM DevNetNeon EVM DevNet
Neon EVM MainNetNeon EVM MainNet
SKALE | Razor NetworkSKALE | Razor Network
SKALE | Calypso NFT Hub TestnetSKALE | Calypso NFT Hub Testnet
SKALE | Block BrawlersSKALE | Block Brawlers
SKALE | Europa Liquidity Hub TestnetSKALE | Europa Liquidity Hub Testnet
SKALE | Nebula Gaming Hub TestnetSKALE | Nebula Gaming Hub Testnet
Zora SepoliaZora Sepolia
SKALE | CryptoBladesSKALE | CryptoBlades
SKALE | Human ProtocolSKALE | Human Protocol
AuroraAurora
Aurora TestnetAurora Testnet
SKALE | Titan Community HubSKALE | Titan Community Hub
SKALE | Chaos TestnetSKALE | Chaos Testnet
SKALE | Nebula Gaming HubSKALE | Nebula Gaming Hub
SKALE | Titan Community Hub TestnetSKALE | Titan Community Hub Testnet
SKALE | Calypso NFT HubSKALE | Calypso NFT Hub
Harmony OneHarmony One
SKALE | Crypto ColosseumSKALE | Crypto Colosseum
SKALE | Europa Liquidity HubSKALE | Europa Liquidity Hub
SKALE | ExordeSKALE | Exorde
Palm TestnetPalm Testnet
PalmPalm
import { ChainIcon } from "connectkit";
import { useAccount, useConfig } from "wagmi";
const { chain } = useAccount();
const { chains } = useConfig()
<ChainIcon id={1} />
<ChainIcon id={chain?.id} unsupported={chains.find((c) => c.id === chain?.id) === undefined} />
<ChainIcon id={chains?.[0].id} />

Below are the various props that can be passed to the ChainIcon component.

id
number
Required

Chain ID

unsupported
boolean

Show unsupported icon

size
number | string
Default is 24

Width and height in pixels, or a string for percentage if necessary (e.g. 50%)

radius
number | string
Default is 50%

Radius in pixels, or a string for percentage (e.g. 50% for fully rounded)

SIWE Button

ConnectKit exports an easy to use Sign In With Ethereum button for you to use within your app.

Just import <SIWEButton> and useSIWE to check if the user has successfully signed in.

import { SIWEButton, useSIWE } from "connectkit";
// This component must be used within the SIWE context provider
const MyComponent = () => {
const { isSignedIn, data } = useSIWE();
return <>
<SIWEButton showSignOutButton />
{isSignedIn && <p>Signed in as {data.address}</p>
</>;
};

Below are the various props that can be passed to the SIWEButton component.

showSignOutButton
boolean

Displays a sign out button after signing in

onSignIn
() => void

Event handler on a successful sign in

,