Ch. 3 · React

React Hydration and Matching Initial Content

React Hydration and Matching Initial Content. Learn the reasoning, a practical example, common mistakes and an interview exercise.

~2 min readadvancedupdated Oct 3, 2026

Hydration attaches behavior to server-rendered markup. The first client render must match the server’s intended initial content before client-only changes occur.

Before you start

You should know how a function component renders JSX, receives props and handles events. Follow the value through render, interaction and the next render. Small snippets below belong inside an existing React application unless they are explicitly shown as complete components.

The practical goal is to reason through this situation: Render a deterministic placeholder, then read browser-only storage after mounting if no server value is available. Read the walkthrough first, then try the interview exercise before opening its answer. The important part is explaining the decision and its consequences, rather than remembering a definition alone.

Step-by-step walkthrough

Step 1: List nondeterministic inputs

Dates, random values, timezone formatting and browser storage can differ between server and client. Find their first-render usage.

Step 2: Share the initial representation

Render the same deterministic value on both sides. Load browser-only information after mounting when no server equivalent is available.

Step 3: Test actual hydration

Check server HTML and the first client render together. Suppressing a warning does not establish that application state is consistent.

Worked scenario

Render a deterministic placeholder, then read browser-only storage after mounting if no server value is available.

const [theme, setTheme] = useState('light');
useEffect(() => {
  setTheme(localStorage.getItem('theme') ?? 'light');
}, []);
JSX

This starts with matching markup but may visibly change theme after mounting. A deliberate pre-hydration theme strategy can avoid that flash; it needs coordinated markup, script and framework behavior rather than an unexplained mismatch.

Common mistake

Random values, time zones or local storage used during initial rendering can create mismatches.

Verify the behavior

Test stored and unstored preferences, blocked storage and differing timezones. Inspect hydration warnings and the visible first paint.

Interview exercise

Render an initial theme reliably.

Answer and reasoning

Prefer a shared server value or a deliberate pre-hydration theme strategy; test markup consistency and avoid hiding unexplained mismatches.

Continue learning

Compare the scenario with the React interview questions and test your understanding with the React MCQs. For terminology and implementation details, consult the reference material.

More in React

read ✓React · hard

React Context Splitting for Performance

Stop a single context value from re-rendering every consumer by splitting state and dispatch and memoizing the provider value.

~2 min readread →
read ✓React · mid

React lazy Loading and Code Splitting

Split bundles with lazy and Suspense, work with default exports, and place boundaries so a chunk loads only when needed.

~2 min readread →
esc