Separate hydration mismatches from key and state identity bugs

Understand the likely causes

• Hydration needs compatible server-generated HTML and the first client description. Time, random values, locale differences, browser-only conditions, or parser-repaired invalid nesting can break that agreement.
• Client state preservation instead depends on component type, position, and key identity. Index or random keys can attach state to the wrong record or remount a subtree. Stable keys do not repair nondeterministic initial HTML.

1. Classify when the disagreement begins

For first-load diagnostics, confirm that the framework uses its intended hydration entry and matched React/renderer versions. Inspect the server response and parsed DOM before client work changes them. For interaction-only defects, edit one row and perform the exact insert, reorder, filter, or selection change. Note whether the state follows the record or the screen position. Do not replace every key or suppress every hydration warning while still unsure which boundary failed. A reduced fixture should retain the triggering data and lifecycle rather than merely resembling the same screenshot.

2. Make initial server and client inputs agree

Move nondeterministic display values into an explicit shared initial input, or use the framework’s documented client-only boundary where that is genuinely required. Do not read a local clock on both sides and assume identical text. The component example uses a fixed synthetic report date; a real server would serialize the reviewed display value consistently. hydrateRoot attaches to React-generated server HTML rather than createRoot replacing it. The module alone is not a full SSR program, so verify it through an isolated server-render-parse-hydrate fixture before claiming the boundary is repaired.

export default function App() { const displayDate = "2026-10-25"; return <main><h1>Report</h1><p>Reviewed: {displayDate}</p></main>; }

Report
Reviewed: 2026-10-25

3. Keep local edits attached to stable records

Use stable record ids at the directly mapped element boundary. The example prepends a known item without changing existing ids, so an uncontrolled input’s edited DOM value remains with its record. Repeated insertion is guarded to avoid duplicate ids. A key is not a normal prop and should not be generated randomly during render. If switching a record should discard a draft, use a deliberate keyed reset and communicate that policy. If drafts must survive filtering out of the tree, store them above the unmounted subtree; keys alone do not retain removed local state.

import { useState } from "react";
export default function App() { const [items, setItems] = useState([{ id: "a", label: "Alpha" }, { id: "b", label: "Beta" }]); return <main><h1>Record identity</h1><button type="button" onClick={() => setItems(xs => xs.some(x => x.id === "c") ? xs : [{ id: "c", label: "Gamma" }, ...xs])}>Prepend Gamma</button><ul>{items.map(item => <li key={item.id}><label>{item.id}<input defaultValue={item.label} /></label></li>)}</ul></main>; }

Editing a then prepending Gamma keeps the edit with a.

4. Verify both lifecycles without blanket suppression

Run a matched SSR fixture through hydration and activate a handler after attachment; capture recoverable errors and unexpected diagnostics. Separately test edited lists under insertion, deletion, reordering, and filtering. Check label ids and focus as well as visible text. useId can support accessibility relationships across matched server/client trees, but it is not a source of record keys. Avoid broad suppressHydrationWarning or random-key remounting as a substitute for analysis. Those shortcuts can conceal the first mismatch while creating lost state or incorrect behavior later.

Keep it from recurring

• Keep deterministic initial data, valid HTML nesting, stable domain keys, and explicit reset boundaries. Maintain separate hydration and interactive-identity regression cases because one cannot prove the other.