Material UI useMediaQuery SSR hydration mismatch between server fallback and client viewport
0 reputation · 17 Jul 2021, 09:17 UTC
Material UI's useMediaQuery hook evaluates CSS media queries in JavaScript, but during server-side rendering it cannot access window.matchMedia and returns the defaultMatches fallback (default false). When the client viewport satisfies the query, the first client render diverges from the server HTML, causing a hydration mismatch in development and a potential layout flash in production.
React 18+ useSyncExternalStore semantics make the server snapshot authoritative for the initial hydration pass, so client-side media state must be reconciled after mount rather than during the first render. The noSsr option suppresses the mismatch by holding the fallback until after mount, but this delays correct responsive behavior and can cause a visible content shift. An unresolved decision is whether to use noSsr, defer media-dependent rendering until after mount, or avoid JavaScript media queries entirely in favor of CSS breakpoints through the sx prop or theme breakpoints.
Because MUI v5, v6, and v7 may differ in default option values and useSyncExternalStore integration, the applicable behavior for a given installation remains version-dependent. Which strategy best balances hydration safety against delayed correct rendering for structural layout decisions, and how should that trade-off be verified for a specific MUI version?