Frontend Integration with ConnectKit

ConnectKit Frontend Integration

ConnectKit by Family is wallet connection UI based on wagmi. If RainbowKit seems overloaded or doesn't fit the design system, ConnectKit offers a more refined and customizable option with the same set of supported wallets.

Installation and Configuration

ConnectKit requires wagmi 2.x and @tanstack/react-query 5.x. All configuration is in createConfig:

import { createConfig, http } from 'wagmi';
import { mainnet, polygon, base } from 'wagmi/chains';
import { getDefaultConfig } from 'connectkit';

const config = createConfig(
  getDefaultConfig({
    chains: [mainnet, polygon, base],
    transports: {
      [mainnet.id]: http('https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY'),
      [polygon.id]: http('https://polygon-mainnet.g.alchemy.com/v2/YOUR_KEY'),
      [base.id]: http('https://base-mainnet.g.alchemy.com/v2/YOUR_KEY'),
    },
    walletConnectProjectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID!,
    appName: 'Your dApp',
    appDescription: 'Description for wallet connection screen',
    appUrl: 'https://your-dapp.xyz',
    appIcon: 'https://your-dapp.xyz/icon.png',
  })
);

getDefaultConfig automatically connects injectors (MetaMask, Rabby, Frame), WalletConnect v2, Coinbase Wallet. WalletConnect Project ID is mandatory — get free from cloud.walletconnect.com.

Provider wraps the application:

'use client'; // Next.js App Router

export function Web3Provider({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <ConnectKitProvider>{children}</ConnectKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

Connect Button

ConnectKitButton is a ready component with full state:

import { ConnectKitButton } from 'connectkit';

// Ready option — minimal code
<ConnectKitButton />

// Custom render via render prop
<ConnectKitButton.Custom>
  {({ isConnected, isConnecting, show, address, ensName }) => (
    <button onClick={show} disabled={isConnecting}>
      {isConnected
        ? ensName ?? `${address?.slice(0, 6)}...${address?.slice(-4)}`
        : 'Connect Wallet'}
    </button>
  )}
</ConnectKitButton.Custom>

Via render prop pattern, ConnectKit fully fits any design system. show opens connection modal.

Theme Customization

ConnectKit supports built-in themes and full customization via customTheme:

<ConnectKitProvider
  theme="midnight" // built-in: auto, web95, retro, soft, midnight
  customTheme={{
    '--ck-font-family': '"Inter", sans-serif',
    '--ck-accent-color': '#6366f1',
    '--ck-accent-text-color': '#ffffff',
    '--ck-border-radius': '12px',
    '--ck-overlay-backdrop-filter': 'blur(8px)',
  }}
>

CSS variables cover colors, radii, fonts, animations. For full control — mode: 'light' | 'dark' or 'auto' to follow system theme.

Working with Wallet State

After connection — standard wagmi hooks:

import { useAccount, useBalance, useChainId, useSwitchChain } from 'wagmi';

function WalletInfo() {
  const { address, isConnected, chain } = useAccount();
  const { data: balance } = useBalance({ address });
  const { switchChain } = useSwitchChain();

  if (!isConnected) return null;

  return (
    <div>
      <p>{address}</p>
      <p>{balance?.formatted} {balance?.symbol}</p>
      {chain?.id !== base.id && (
        <button onClick={() => switchChain({ chainId: base.id })}>
          Switch to Base
        </button>
      )}
    </div>
  );
}

Frequent Integration Problems

Hydration mismatch — isConnected is always false on server, can be true on client. Solution: use mounted state or wagmi hook useHydrated (if available). Alternative — render wallet-dependent UI only after useEffect.

WalletConnect modal doesn't open on mobile — need correct appUrl in config matching origin. WalletConnect v2 checks origin.

Safe{Wallet} support — if dApp is used as part of multisig, need to add safeConnector from @gnosis.pm/safe-apps-wagmi separately, ConnectKit doesn't include it by default.

Timeline Guidelines

Full ConnectKit integration into existing React/Next.js project, including theme customization and testing on multiple wallets — 1-2 days. With custom button render, chain switching handling and Safe{Wallet} support — up to 3 days.