Two Trees: Hydration Explained

You build a date display component. It works perfectly in development. You deploy to production. Users see the page flicker, or see a timestamp that's wrong for a split second, or the browser console fills with warnings you never saw locally.

The culprit: hydration mismatch. The HTML your server rendered doesn't match what React rendered in the browser — and React throws away the server HTML and re-renders from scratch.

When you use SSR (Next.js, Remix, etc.), your page loads in two phases:

1. Server renders HTML — React runs on the server and generates HTML string. Browser receives and displays it immediately (fast first paint).
2. React "hydrates" the HTML — React runs in the browser, builds its virtual DOM, and attaches to the server HTML.

These two runs must produce identical HTML. If they differ — even by one character — you have a mismatch. React either ignores it (silent, with a potential flash) or re-renders the whole subtree (visible flicker).

The Date trap

// ❌ new Date() on server at 10:00:00 !== new Date() on client at 10:00:01
function LastUpdated() {
  return <span>Updated: {new Date().toLocaleTimeString()}</span>;
}

The window trap

// ❌ window is undefined on server — crashes or renders differently
function ThemeProvider() {
  const theme = window.localStorage.getItem('theme') || 'light';
  return <div data-theme={theme}>{children}</div>;
}

The random ID trap

// ❌ Different UUID on server vs client → id mismatch
function FormField({ label }) {
  const id = Math.random().toString(36).slice(2);
  return (
    <>
      <label htmlFor={id}>{label}</label>
      <input id={id} />
    </>
  );
}

Fix 1: useEffect for client-only values

// ✅ Server renders null; client renders the time after mount
function LastUpdated() {
  const [time, setTime] = useState(null);
  useEffect(() => {
    setTime(new Date().toLocaleTimeString());
  }, []);
  if (!time) return null; // or a placeholder
  return <span>Updated: {time}</span>;
}

Fix 2: stable IDs with React 18's useId

// ✅ useId generates the same stable ID on server and client
import { useId } from 'react';
function FormField({ label }) {
  const id = useId();
  return (
    <>
      <label htmlFor={id}>{label}</label>
      <input id={id} />
    </>
  );
}

Fix 3: suppress intentional mismatches

// ✅ Tell React this element will differ — intentional, documented
<time dateTime={date.toISOString()} suppressHydrationWarning>
  {date.toLocaleString()} {/* locale may differ server/client */}
</time>

Toggle "Broken" to see a component using Math.random() — it renders differently each time (simulating server vs client mismatch). "Fixed" uses useId and stays stable.

The warning text is your friend: React logs the expected vs received values. Grep your component tree for Math.random(), Date.now(), new Date(), and any window.* reads in render functions.