A server-rendered React app chooses its theme by reading localStorage during render. In the browser it briefly shows the light theme and logs a hydration mismatch. Explain the cause and the options you would consider for fixing it.

## Why this is the most instructive mismatch Time and randomness mismatches are accidents. This one is architectural: the value genuinely lives only in the browser, so no amount of care makes the server's first render correct. The interviewer is checking whether you understand that hydration requires *agreement*, not correctness — and that you know the fix is to choose what both sides will agree on. ## What actually happens On the server, `typeof window === 'undefined'`. Code like `localStorage.getItem('theme')` either throws or, more commonly, sits behind a guard that falls back to `'light'`. The HTML ships with the light theme. In the browser the same component runs again for hydration, this time reading `'dark'` from storage, and renders a different class. React finds the disagreement, reports a hydration error, and client-renders that subtree. The user sees light, then dark — and the flash is visible even when the mismatch is later suppressed, because the *server HTML painted first*. Silencing the warning does not remove the flash; only rendering the right thing before paint does. ## Option 1 — deterministic first render, correct after mount ```jsx function useTheme() { const [theme, setTheme] = useState('light'); // matches the server useEffect(() => { const stored = localStorage.getItem('theme'); if (stored) setTheme(stored); }, []); return theme; } ``` Correct by construction, because effects never run on the server and run after hydration commits on the client. The cost is one flash of the wrong theme. Acceptable for a small widget; poor for a full-page theme. ## Option 2 — useSyncExternalStore with a server snapshot `useSyncExternalStore` takes a subscribe function, a client snapshot getter, and a server snapshot getter. The third one is used during server rendering *and* during the client's hydration render, which is precisely the property that prevents mismatches: both runs read the same deterministic value. After hydration, React switches to the client snapshot and the subscription keeps it in sync. The discipline this imposes is the useful part — the server snapshot must return a value the server could actually have produced. If you cheat and read `localStorage` from it, you are back to a mismatch. The flash remains; what you gain is a single, consistent way to read a browser-only source across the app, one that also handles updates from other tabs. ## Option 3 — decide before React renders The only way to avoid the flash is to have the correct value applied before first paint. A tiny synchronous script in the document head reads storage and sets an attribute: ```html <script> document.documentElement.dataset.theme = localStorage.getItem('theme') || 'light'; </script> ``` CSS keys off `[data-theme='dark']`, so the very first paint is correct. React never renders that attribute, so there is nothing to mismatch. When React *does* own the element that the script mutates, put `suppressHydrationWarning` on it — this is the textbook legitimate use, because the difference is intentional and understood. Note the tradeoff: a blocking inline script costs a little render-blocking time, and it must be idempotent with whatever React later renders. ## Option 4 — make it server-known If the preference lives in a cookie rather than `localStorage`, the server receives it with the request, renders the right theme, and both runs agree with no flash and no special hooks. This is usually the best answer for anything that affects above-the-fold rendering — the real problem was choosing a storage mechanism the server cannot see. ## The general rule The same analysis covers every browser-only read during render: `matchMedia` for a media query or `prefers-color-scheme`, `navigator.userAgent` for device branching, `window.innerWidth` for a responsive layout, feature detection. Each of them makes the client's first render depend on something the server cannot know. So the reflexes worth naming: - Never branch a render on `typeof window` to produce different output — that guarantees a mismatch. - Prefer CSS for anything CSS can express: media queries and `prefers-color-scheme` need no JavaScript and no server knowledge, so they never mismatch. - If the value must come from JavaScript, decide whether it can move to a cookie (server-known), be applied before hydration (no flash), or be corrected after mount (flash, simplest). A candidate who lists those three destinations — server-known, pre-hydration, post-hydration — has answered the question, whatever they pick.