useMediaQuery SSR fallback behavior remains undecided in MUI
0 reputation · 08 Jan 2020, 21:59 UTC
The useMediaQuery hook reads breakpoints from the theme and relies on window.matchMedia, which is absent during server‑side rendering. Without a custom ssrMatchMedia function supplied via the theme, the hook defaults to false, often causing hydration mismatches in frameworks like Next.js. The MUI team has discussed adding a built‑in ssrMatchMedia implementation to the default theme but has not reached consensus, leaving the fallback strategy as an open design decision.
Developers must currently choose between providing a project‑specific ssrMatchMedia, guarding the hook with typeof window !== 'undefined', or accepting the initial false render and a client‑side update. Each approach carries trade‑offs for bundle size, layout shift, and API surface.
What is the current status of the proposed default ssrMatchMedia implementation? Are there any documented workarounds that avoid both hydration warnings and a flash of incorrect layout? Does the MUI roadmap indicate a timeline for resolving this behavior?