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 / Hook	Description
<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 Prop	Description	Light/Dark Mode Support
`default`	Default theme
`web95`	Web95 theme
`retro`	Retro theme
`soft`	Soft theme
`midnight`	Midnight theme
`minimal`	Minimal theme
`rounded`	Rounded 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 Prop	Description
`auto`	Either dark or light that matches the user's system color scheme
`dark`	Dark mode
`light`	Light 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

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:

Argument	Type	Description
address	string	The connected wallet address.
connectorId	string	The 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 Name	Chain ID	Chain Icon	Unsupported
	null
Ethereum	Ethereum
Goerli	Goerli
OP Mainnet	OP Mainnet
Flare Mainnet	Flare Mainnet
Coston	Coston
Songbird Mainnet	Songbird Mainnet
Cronos	Cronos
Telos	Telos
Telos	Telos
XinFin Network	XinFin Network
Apothem Network	Apothem Network
BNB Smart Chain	BNB Smart Chain
Syscoin Mainnet	Syscoin Mainnet
OKC	OKC
Binance Smart Chain Testnet	Binance Smart Chain Testnet
Gnosis	Gnosis
Coston2	Coston2
Polygon	Polygon
Fantom	Fantom
zkSync Era Testnet	zkSync Era Testnet
Boba Network	Boba Network
Filecoin Mainnet	Filecoin Mainnet
zkSync Era	zkSync Era
PulseChain	PulseChain
Optimism Goerli	Optimism Goerli
Metis Goerli	Metis Goerli
Taraxa Mainnet	Taraxa Mainnet
Taraxa Testnet	Taraxa Testnet
Wanchain	Wanchain
PulseChain V4	PulseChain V4
5ireChain Thunder Testnet	5ireChain Thunder Testnet
Wanchain Testnet	Wanchain Testnet
Zora Goerli Testnet	Zora Goerli Testnet
Bronos Testnet	Bronos Testnet
Bronos	Bronos
Metis	Metis
Polygon zkEVM	Polygon zkEVM
Moonbeam	Moonbeam
Moonriver	Moonriver
Moonbase Alpha	Moonbase Alpha
Localhost	Localhost
Polygon zkEVM Testnet	Polygon zkEVM Testnet
Dogechain	Dogechain
Filecoin Hyperspace	Filecoin Hyperspace
Crossbell	Crossbell
Fantom Testnet	Fantom Testnet
Nexi	Nexi
IoTeX	IoTeX
IoTeX Testnet	IoTeX Testnet
MEVerse Chain Testnet	MEVerse Chain Testnet
MEVerse Chain Mainnet	MEVerse Chain Mainnet
Canto	Canto
Shardeum Sphinx	Shardeum Sphinx
Klaytn	Klaytn
Base	Base
Evmos Testnet	Evmos Testnet
Evmos	Evmos
Gnosis Chiado	Gnosis Chiado
HAQQ Mainnet	HAQQ Mainnet
Cannoli	Cannoli
Foundry	Foundry
Hardhat	Hardhat
Arbitrum One	Arbitrum One
Celo	Celo
Avalanche Fuji	Avalanche Fuji
Avalanche	Avalanche
Alfajores	Alfajores
DFK Chain	DFK Chain
HAQQ Testedge 2	HAQQ Testedge 2
Linea Goerli Testnet	Linea Goerli Testnet
Polygon Mumbai	Polygon Mumbai
Base Goerli	Base Goerli
Filecoin Calibration	Filecoin Calibration
Arbitrum Goerli	Arbitrum Goerli
Scroll Testnet	Scroll Testnet
Zhejiang	Zhejiang
Zora	Zora
Sepolia	Sepolia
SKALE \| Razor Network	SKALE \| Razor Network
SKALE \| Calypso NFT Hub Testnet	SKALE \| Calypso NFT Hub Testnet
SKALE \| Block Brawlers	SKALE \| Block Brawlers
SKALE \| Europa Liquidity Hub Testnet	SKALE \| Europa Liquidity Hub Testnet
SKALE \| Nebula Gaming Hub Testnet	SKALE \| Nebula Gaming Hub Testnet
SKALE \| CryptoBlades	SKALE \| CryptoBlades
SKALE \| Human Protocol	SKALE \| Human Protocol
Aurora	Aurora
Aurora Testnet	Aurora Testnet
SKALE \| Titan Community Hub	SKALE \| Titan Community Hub
SKALE \| Chaos Testnet	SKALE \| Chaos Testnet
SKALE \| Nebula Gaming Hub	SKALE \| Nebula Gaming Hub
SKALE \| Titan Community Hub Testnet	SKALE \| Titan Community Hub Testnet
SKALE \| Calypso NFT Hub	SKALE \| Calypso NFT Hub
Harmony One	Harmony One
SKALE \| Crypto Colosseum	SKALE \| Crypto Colosseum
SKALE \| Europa Liquidity Hub	SKALE \| Europa Liquidity Hub
SKALE \| Exorde	SKALE \| 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

API Reference

Components and Hooks

ConnectKitProvider

theme

mode

customTheme

Connect Wallet Button variables

Primary Button variables

Secondary Button variables

Tertiary Button variables

Modal variables

Text variables

Miscellaneous variables

options

onConnect

onDisconnect

ConnectKitButton

ConnectKitButton.Custom

Render Props

Hooks

useModal

useSIWE

useChains

Additional Components

Avatar

Chain Icon

SIWE Button

On this page