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 WagmiConfig. 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

Open the modal on the About page.

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
CronosCronos
TelosTelos
TelosTelos
XinFin NetworkXinFin Network
Apothem NetworkApothem Network
BNB Smart ChainBNB Smart Chain
Syscoin MainnetSyscoin Mainnet
OKCOKC
Binance Smart Chain TestnetBinance Smart Chain Testnet
GnosisGnosis
Coston2Coston2
PolygonPolygon
FantomFantom
zkSync Era TestnetzkSync Era Testnet
Boba NetworkBoba Network
Filecoin MainnetFilecoin Mainnet
zkSync ErazkSync Era
PulseChainPulseChain
Optimism GoerliOptimism Goerli
Metis GoerliMetis Goerli
Taraxa MainnetTaraxa Mainnet
Taraxa TestnetTaraxa Testnet
WanchainWanchain
PulseChain V4PulseChain V4
5ireChain Thunder Testnet5ireChain Thunder Testnet
Wanchain TestnetWanchain Testnet
Zora Goerli TestnetZora Goerli Testnet
Bronos TestnetBronos Testnet
BronosBronos
MetisMetis
Polygon zkEVMPolygon zkEVM
MoonbeamMoonbeam
MoonriverMoonriver
Moonbase AlphaMoonbase Alpha
LocalhostLocalhost
Polygon zkEVM TestnetPolygon zkEVM Testnet
DogechainDogechain
Filecoin HyperspaceFilecoin Hyperspace
CrossbellCrossbell
Fantom TestnetFantom Testnet
NexiNexi
IoTeXIoTeX
IoTeX TestnetIoTeX Testnet
MEVerse Chain TestnetMEVerse Chain Testnet
MEVerse Chain MainnetMEVerse Chain Mainnet
CantoCanto
Shardeum SphinxShardeum Sphinx
KlaytnKlaytn
BaseBase
Evmos TestnetEvmos Testnet
EvmosEvmos
Gnosis ChiadoGnosis Chiado
HAQQ MainnetHAQQ Mainnet
CannoliCannoli
FoundryFoundry
HardhatHardhat
Arbitrum OneArbitrum One
CeloCelo
Avalanche FujiAvalanche Fuji
AvalancheAvalanche
AlfajoresAlfajores
DFK ChainDFK Chain
HAQQ Testedge 2HAQQ Testedge 2
Linea Goerli TestnetLinea Goerli Testnet
Polygon MumbaiPolygon Mumbai
Base GoerliBase Goerli
Filecoin CalibrationFilecoin Calibration
Arbitrum GoerliArbitrum Goerli
Scroll TestnetScroll Testnet
ZhejiangZhejiang
ZoraZora
SepoliaSepolia
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
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
import { ChainIcon } from "connectkit";
import { useNetwork } from "wagmi";
const { chain } = useNetwork();
<ChainIcon id={1} />
<ChainIcon id={chain?.id} unsupported={chain?.unsupported} />

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