gotchajavascriptMajor

wagmi: wallet connection with ConnectKit causes hydration mismatch in Next.js

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

wagmi 2.x, ConnectKit 1.x, Next.js 14+

wagmiconnectkitrainbowkithydrationnextjsssrwallet connect

nextjs

Error Messages

Error: Hydration failed because the initial UI does not match what was rendered on the server

Problem

Using ConnectKit or RainbowKit with wagmi in Next.js causes React hydration errors because wallet state differs between server render and client render.

Solution

Wrap your ConnectKit/RainbowKit provider usage with a mounted state check or use the suppressHydrationWarning prop on the body. The recommended approach is to render wallet-dependent UI only after the component has mounted on the client.

Why

The server has no knowledge of the user's wallet state. Any component that renders differently based on wallet connection will mismatch between SSR output and client hydration.

Gotchas

Simply adding 'use client' does not fix hydration issues if the component is inside the app router
ConnectKit's ConnectKitButton must be rendered client-side only
suppressHydrationWarning only suppresses the warning, it does not fix the underlying flash of incorrect content

Code Snippets

Mount guard to prevent hydration mismatch

'use client';
import { useState, useEffect } from 'react';
import { ConnectKitButton } from 'connectkit';

export function WalletButton() {
  const [mounted, setMounted] = useState(false);
  useEffect(() => setMounted(true), []);
  if (!mounted) return null;
  return <ConnectKitButton />;
}

Context

Building a Next.js dApp with server-side rendering enabled

Revisions (0)

No revisions yet.