Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

connectkit

family49.4kBSD-2-Clause license1.9.0TypeScript support: included

Connecting a wallet, made simple.

ens, react-hook, blockchain, hooks, family, ethereum, react

readme

connectkit

ConnectKit

ConnectKit is a powerful React component library for connecting a wallet to your dApp. It supports the most popular connectors and chains out of the box and provides a beautiful, seamless experience.

Features

  • 💡 TypeScript Ready — Get types straight out of the box.
  • 🌱 Ecosystem Standards — Uses top libraries such as wagmi.
  • 🖥️ Simple UX — Give users a simple, attractive experience.
  • 🎨 Beautiful Themes — Predesigned themes or full customization.

and much more...

Quick Start

Get started with a ConnectKit + wagmi + viem project by running one of the following in your terminal:

npm

npx create-react-app my-app --template cra-template-connectkit

yarn

yarn create react-app my-app --template cra-template-connectkit

pnpm

pnpm dlx create-react-app ./my-app --template cra-template-connectkit

Documentation

You can find the full ConnectKit documentation in the Family docs here.

API Reference

You can find the full API Reference in the Family docs here.

Examples

There are various runnable examples included in this repository in the examples folder:

Try in CodeSandbox

You can try out some ConnectKit examples directly in your browser through CodeSandbox:

Running Examples Locally

Clone the ConnectKit project and install the necessary dependencies:

$ git clone git@github.com:family/connectkit.git
$ cd connectkit
$ yarn install

and start the code bundler:

$ yarn dev:connectkit
$ yarn dev:connectkit-next-siwe

and then simply select the example you'd like to run:

$ yarn dev:vite # Vite
$ yarn dev:nextjs # Next.js
$ yarn dev:nextjs-siwe # Next.js with SIWE
$ yarn dev:cra # Create React App

Contribute

Before starting on anything, please have a read through our Contribution Guidelines.

Twitter

Follow @family on Twitter for the latest updates on ConnectKit.

License

See LICENSE for more information.

changelog

1.9.0

We're thrilled to announce a major upgrade to ConnectKit—designed to make onboarding and navigating Ethereum simpler and safer than ever.

Introducing Family Accounts, simplified onboarding for new users.

Learn more by reading the announcement here.

New

Improved

  • Updates chain logos for zora, base, optimism and lens.

1.8.2

This update includes improvements to the CoinbaseWalletSDK connect popup and MockConnector.

Fixed

  • CoinbaseWalletSDK connect popup now works on first interaction.
  • MockConnector now working as intended.

1.8.1

This update adds additional localisations, and improves the stability of Coinbase Wallet and MetaMask connections.

New

  • Localisations for Vietnamese, Turkish, Persian, Arabic, Russian, Estonian and Catalan.

Fixed

  • CoinbaseWalletSDK connect popup being blocked on iOS Safari.
  • Revert back to using MetaMaskSDK for MetaMask connections.
  • Desktop deeplinking for LedgerLive.

1.8.0

This update adds support for Coinbase Smart Wallet, adds additional support for the latest versions of peer dependencies wagmi and viem, and removes the dependency ethers from connectkit-next-siwe in favor of viem's SIWE implementation.

New

Updated

  • Changed default setting for enforceSupportedChains to false to allow for a better default user and developer experience.
  • Updates peer dependency viem to >=2.13.x.

Deprecated

1.7.3

This update fixes a few bugs and improves the stability of the QR code generation for WalletConnect and Coinbase Wallet.

Fixed

  • ENS resolution when mainnet not found in createConfig.
  • WalletConnectConnector regenerates QR codes when a user disconnects and attempts to reconnect their wallet.
  • CoinbaseConnector generated QR code now using a better supported URI.
  • Configured projectId now being passed to the WalletConnectConnector when opening "More" UI in mobile view.

Removed

  • References to WalletConnectLegacy (WalletConnect v1).

1.7.2

This update fixes an issue with the order of React Hooks, and improves the stability of the SIWE Provider.

Improved

  • Remove initialData from useQuery Hooks.

Fixed

  • Fix order of Hooks in useChainIsSupported.

1.7.1

This update fixes a bug where the chain was incorrectly detected as unsupported when only one chain is configured.

Improved

  • Switch to using wagmi storage for detecting the last used connector ID.
  • Filter out duplicate connectors from the list of available connectors.
  • More defined overflow divider for the connector list.

Fixed

  • Chain being incorrectly detected as unsupported when only one chain is configured.
  • Ability to override the "Other Wallets" button text.
  • SIWE Provider stability and returned types when returning nonce and session from the server.

1.7.0

This update moves peer dependencies wagmi and viem up to their latest versions.

Note

This version of ConnectKit has breaking changes. Make sure your application is compatible by following the ConnectKit migration guide, and the wagmi 2.x migration guide.

New

  • Updates peer dependency wagmi to 2.x.
  • Updates peer dependency viem to 2.x.
  • New peer dependency @tanstack/react-query.

Deprecated

  • Removes dependency mipd.

1.6.0

This update adds EIP-6963 support for enhanced wallet discovery and improves the functionality and developer experience of using ConnectKit.

New

  • Support for EIP-6963.
    • Includes dependency mipd for EIP-6963 TypeScript utilities, built by the team at wevm (creators of wagmi and viem).
  • Added Zerion extension support.

Improved

  • Hide SIWE tooltip when using hideTooltips option.

1.5.3

This update adds branding support for additional detectable injected connectors and improves the functionality and developer experience of using ConnectKit.

New

  • Rainbow extension support.
  • Exports defaultConnectors

Improved

  • Added name in header for injected wallet when detected by wagmi.

Fixed

  • Fixed UI overflow in switch network tab.
  • Fixed text overlap in switch network buttons.
  • Provide exports.types in package.json

1.5.2

This update addresses a few bugs and improves the overall experience of ConnectKit.

Fixed

  • Added wcm-modal tag to css variable override.
  • Fixed flash of unstyled content on the <ChainIcon> component.
  • Fixed bug where the modal wouldn't open if the configuration didn't include the InjectedConnector.

1.5.1

This update improves how ConnectKit handles multiple injected wallets.

Improved

  • Better support when dealing with multiple injected wallets.

Fixed

  • Updated --w3m-z-index to --wcm-z-index to align with latest wagmi connectors.

1.5.0

This update improves the developer experience of using ConnectKit by upgrading the peer dependency, wagmi, to version 1.1.x, updating viem to version 1.x.x, and providing additional wallet branding support.

New

Improved

  • Better support for injected wallets.
  • Updated Phantom branding.

Misc

  • Fixed typo in Safe website URL.
  • Updated some SVGs to be more performant with JSX.
  • Fixed arrows in buttons not inheriting hover colors.

1.4.0

This update improves the developer experience of using ConnectKit by upgrading the peer dependency wagmi up a version to 1.x.x, and removes the peer dependency ethers in favor of viem.

Note

This version of ConnectKit has breaking changes. Make sure your application is compatible by following the migration guide.

New

  • Updates peer dependency wagmi to 1.x.x.
  • Adds peer dependency viem.

Deprecated

  • Removes peer dependency on ethers.

1.3.0

WalletConnect v1 is scheduled to shut down and will be no longer be supported after June 28 2023. It is advised to update your dApps immediately to support WalletConnect v2.

Read the announcement

Note

This version of ConnectKit has breaking changes. Make sure your application is compatible by following the migration guide.

New

  • Adds support for WalletConnect v2.

Deprecated

  • Removes default support for WalletConnect v1.

1.2.4

This update adds branding support for additional detectable injected connectors and improves the functionality and developer experience of using ConnectKit with Sign In With Ethereum.

New

  • Branding for additional injected connectors:
    • Frame
    • Phantom
    • Dawn
  • connectkit-next-siwe version 0.1.1 add adds afterNonce afterVerify afterSession and afterLogout callbacks to the server-side SIWE helper functions.
  • connectkit-next-siwe version 0.2.0 updates peer dependency siwe to 2.0.0.

1.2.3

This update adds some minor quality of life features to ConnectKit.

Improved

  • Updated styling of the switch chain page for better readability.
  • Adds prefix to LocalStorage keys to avoid collisions with other apps.
  • Restyled documentation site to make following guides even easier.

1.2.2

This update improves the functionality and developer experience of using ConnectKit and moves the peer dependency wagmi up a version to 0.12.x.

Note

This update does not yet include support for WalletConnect 2.0.

New

  • Adds a Recent badge to the most recently used connector button by a user. This helps returning users reconnect easily and save time.
  • Introduce SafeConnector into the default configuration for better support for Safe Apps. Learn more about this connector in the wagmi docs.
  • Convenient onConnect and onDisconnect callbacks on the ConnectKitProvider component and useModal Hook.
  • Added dedicated overlayBlur prop to ConnectKitProvider to allow for blurring the background when the modal is open.
  • Update peer dependency wagmi to version 0.12.x.

Improved

  • Added support for Node 14.
  • Improved aria-labels on buttons for better accessibility.
  • Icons within buttons are now properly horizontally centered on FireFox.
  • Optimise some of the SVGs used in ConnectKit.

Fixed

  • Fixed a bug where changing accounts when signed-in with Ethereum would cause an infinite loop (thanks JamieLottering).

1.2.1

This update improves the functionality and developer experience of using ConnectKit and moves the peer dependency wagmi up a version to 0.11.x. This update does not yet include support for WalletConnect 2.0 (wagmi 0.12.x)

Note

This version of wagmi has breaking changes. Make sure your application is compatible by following wagmi's migration guide.

New

  • Update peer dependency wagmi to version 0.11.x (thanks Songkeys).
  • Add new pt-BR translations (thanks LuwkasLima).
  • Include new hideBalance option to hide the wallet balance from the profile view.
  • Include new enforceSupportedChains option to disable the forced network switching UX when connected to an unsupported chain.
  • Include new disableSiweRedirect option to disable the redirect to the SIWE page when a wallet connects.
  • Include new functions from the useModal Hook to choose a page to navigate to on open.
    • The openSIWE() function accepts a boolean, if true it will initiate the wallet SIWE signing request at the same time as opening the modal.
  • Add logos for the following chains:
    • Optimism Goerli
    • Telos + Testnet
    • Aurora + Testnet
    • Avalanche + Fuji Testnet
    • Foundry
    • Gnosis
    • Evmos + Testnet
    • BNB Smart Chain + Testnet
    • Sepolia
    • Taraxa + Testnet
    • zkSync + Testnet
    • Celo + Alfajores Testnet
    • Canto
    • Fantom + Testnet
    • Filecoin + Hyperspace + Calibration Testnets
    • Flare + Coston2 testnet
    • Metis + Testnet
    • IoTeX + Testnet

Improved

  • Update testbench for better developer experience.
  • Improve logic for isConnecting within the Custom ConnectKitButton.
  • Replace getGlobalChains with useChains Hook
  • Tidy up some internal component structure and include a few useful dev updates (thanks pugson).
  • Export useIsMounted and Context (thanks shahruz).

1.2.0

This update improves the functionality and developer experience of using ConnectKit with Sign In With Ethereum.

New

  • Add onSignIn and onSignOut handlers for useSIWE and the SIWE provider.

Improved

  • Separate the SIWE helper functions into more friendlier client and server configurations.
  • Improved the useSIWE hook to allow for better dev access to SIWE functionality.

1.1.4

This update adds some minor quality of life features to ConnectKit.

Improved

  • Included shimChainChangedDisconnect option to MetaMaskConnector to automatically disconnect the wallet when the chain changes in particular version of MetaMask (thanks Songkeys).
  • Added size prop to ChainIcon component to allow for custom sizing (thanks JamieLottering).
  • Exported type ConnectKitOptions for better TypeScript support when creating a wagmi client (thanks ryanberckmans).
  • Included chain to ConnectKitButton.custom to allow for chains to be passed to custom buttons.

1.1.3

This update fixes compatibility issues that were found with Next 13's default configuration. If you would like to use previous versions of ConnectKit you will need to make sure your application supports Terser compression.

Removed

  • Terser build compression.

Improved

  • Synced dev and prod rollup configs to avoid environment mismatching.
  • Next.js 13 config no longer requires Terser support (swcMinify: false).

1.1.2

This update moves the peer dependency wagmi up to the latest version (0.10.x). This does not yet include support for WalletConnect 2.0.

New

  • Update peer dependency wagmi to version 0.10.x.
  • New options for ethereumOnboardingUrl and walletOnboardingUrl to custom change the Learn More and About Wallets call to actions.

Fixed

  • Remove sunset ethhub.io links and replace with ethereum.org links.

Improved

  • Update to chain handling to allow devs access to the configured chains using getGlobalChains.
  • Update to allow turning off the default targeted chainId to let wallets connect using their currently active chain.
    • This can be done by setting initialChainId to 0 within the getDefaultClient helper function.

1.1.1

This update moves the peer dependency wagmi up to the latest version (0.9.x).

Note

This version of wagmi has breaking changes. Make sure your application is compatible by following wagmi's migration guide.

1.1.0

This update moves the peer dependency wagmi up to the latest version (0.8.x).

Note

This version of ConnectKit has breaking changes. Make sure your application is compatible by following the migration guide.

New

  • Update peer dependency wagmi to version 0.8.x.

Removed

  • Removed CommonJS support to work within wagmi's 0.8.x requirements.

1.0.1

This update introduces localisations to ConnectKit.

New

  • Added a language option under options that allows developers to include localisation support—starting with options for Spanish, French, Japanese and Chinese (Simplified).

Fixed

  • Removed layered background on the injected connectors flow to allow for transparent modal background colors (issue #41).

1.0.0

This update introduces Sign In With Ethereum and other helpful changes and additions to make your app better than ever.

New

  • Added Sign In With Ethereum support with a Next.js package to help with quick setup.
  • Added an <Avatar /> component for developers to utilize the default ConnectKit avatar.
  • Created a <CustomAvatar /> component for developers to override the default avatar.
  • Added a walletConnectCTA option under options to choose whether to display the 'Copy to Clipboard' option under the WalletConnect QR code.
  • Added a initialChainId option under options to customize the initially connected chain.
  • Added a --ck-overlay-backdrop-filter property for custom themes to utilise the backdrop-filter property on the modal overlay.
  • Added a new nouns theme to the built-in default themes ⌐◨-◨

Fixed

  • Corrected some variable names for the secondary buttons.

Improved

  • Updated Gnosis Safe to reflect their recent rebrand to 'Safe'.
  • Wrong Network UX now suggests a network change and no longer blocks users from changing networks.
  • Enabled TypeScript strict mode (bumped target to es6).
  • Line break for "Scan with Coinbase Wallet" title if the font is too wide.
  • Fix an SVG stop-color vs stopColor issue (thanks @keon).
  • Added icon support for Arbitrum Goerli (thanks @mirshko).
  • Unknown chain icon fallback (thanks @Bridgerz).

Removed

  • Unnecessary SVGs and logos.

0.0.2

New

  • NetworkButton component for making network switching easier, opens as a dropdown
  • BalanceButton component for displaying the balance of the connected wallet (in a button), opens the profile modal
  • Balance component for displaying the balance of the connected wallet, intentionally left mostly unstyled
  • Avatar component for displaying a wallets ens avatar, with a fallback to a nice gradient based on that ens/address as a seed

General

  • Add buffer as a dependency to ConnectKit. Developers no longer need to maintain their own installation of the buffer package.
  • Remove Slope as a suggested wallet in the UI
  • Default connector buttons in the modal are now filled instead of previously stroked
  • Improvements and update to the default themes
  • Wallet Connection now requests the first chain in the chains array given when creating your client configuration

ConnectKitButton

  • Add props to <ConnectKitButton /> for additional button configuration
    • label to customize the connect button text/label
    • showBalance to show wallet balance when connected (false default)
    • showAvatar to show ENS/wallet avatar when connected (true default)

ConnectKitProvider

  • Add disclaimer option under options that accepts a string or ReactNode to be displayed in the first screen of the modal when a wallet is not connected

Bug Fixes

  • Single chain tooltip was not inherting theme correctly

Misc.

  • Visual debug message in the UI when there is a custom client config setup for CoinbaseWalletConnector that does not have headlessMode:true