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.
useModal()Programatically control some aspects of the modal.

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.

hideTooltips
boolean

Hide any tooltips that would normally appear

hideQuestionMarkCTA
boolean

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

hideNoWalletCTA
boolean

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

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

embedGoogleFonts
boolean
Default is false

Automatically embeds Google Font of the current theme.

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.

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.

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.

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.

initialChainId
number
Default is the first chain in your client 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.

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

Link to a resource for learning more about Ethereum.

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

Link to a resource for learning more about Wallets.

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

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

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

useModal Hook

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

The useModal Hook is experimental and may change in the future to allow for more programmatic control over the behavior of the modal. For now it only surfaces a function to show/dismiss the modal.

Props

open
boolean

Whether or not the modal is open.

setOpen
(boolean) => void

Programatically show/dismiss the modal.

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.

1import { Avatar } from "connectkit";
2
3<Avatar name="vitalik.eth" />
4<Avatar name="vitalik.eth" size={64} radius={10} />
5<Avatar name="vitalik.eth" size={32} radius={0} />
6<Avatar address="0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" size={16} />
7<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
Arbitrum OneArbitrum One
Arbitrum GoerliArbitrum Goerli
AvalancheAvalanche
Avalanche FujiAvalanche Fuji
BNB Smart ChainBNB Smart Chain
Binance Smart Chain TestnetBinance Smart Chain Testnet
FantomFantom
Fantom TestnetFantom Testnet
FoundryFoundry
GoerliGoerli
HardhatHardhat
LocalhostLocalhost
EthereumEthereum
OptimismOptimism
Optimism GoerliOptimism Goerli
PolygonPolygon
Polygon MumbaiPolygon Mumbai
SepoliaSepolia
1import { ChainIcon } from "connectkit";
2import { useNetwork } from "wagmi";
3
4const { chain } = useNetwork();
5
6<ChainIcon id={1} />
7<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

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.

1import { SIWEButton, useSIWE } from "connectkit";
2
3// This component must be used within the SIWE context provider
4const MyComponent = () => {
5 const { signedIn, address } = useSIWE();
6 return <>
7 <SIWEButton showSignOutButton />
8 {signedIn && <p>Signed in as {address}</p>
9 </>;
10};

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

getGlobalChains

If using ConnectKit's getDefaultClient helper function, you can access the configured chains via this convenient function. This works well with the ChainIcon component.

1import { getGlobalChains, ChainIcon } from "connectkit";
2
3const MyComponent = () => {
4 const chains = getGlobalChains();
5 return (
6 <>
7 <p>This dApp is supported on the following chains:</p>
8 {chains.map((chain) => (
9 <div key={chain.id}>
10 <ChainIcon id={chain.id} />
11 <span>{chain.name}</span>
12 </div>
13 ))}
14 </>
15 );
16};