[BUG] useMediaQuery SSR case

[quantizor]

Describe the bug

I want the server to render in mobile mode for SSR and then, after mount, I want to run the actual media query and have the UI update without a hydration mismatch. It doesn't seem to be possible to arrive at this behavior with the current hook setup.

To Reproduce

const isMobile = useMediaQuery("(max-width: 768px)", {
  defaultValue: true,
  initializeWithValue: false,
});

Expected behavior

1. SSR occurs, isMobile is set to true due to defaultValue
2. Page loads, isMobile remains true
3. Initial mount completes, hook re-evaluates and determines that the page is >768px so isMobile is updated to false, UI updates to the correct end state

Additional context

I've tried various combinations of defaultValue and initializeWithValue, none seem to arrive at the desired behavior. It's very important that the final evaluation happens after mount such as to not cause a rehydration warning/error.

[aquaticcalf]

interesting,

the issue is that even with initializeWithValue: false, the hook still evaluates the media query during the layout effect phase, which can trigger hydration warnings

what's happening here is :

1. SSR renders with isMobile = true (your defaultValue)
2. client initial render matches with isMobile = true
3. useIsomorphicLayoutEffect immediately calls handleChange() and evaluates the real media query, potentially during hydration

a potential solution could be to add a delayEvaluation option that postpones the media query check until after the component has fully mounted :

const isMobile = useMediaQuery("(max-width: 768px)", {
  defaultValue: true,
  initializeWithValue: false,
  delayEvaluation: true // new option?
})

this would use useEffect instead of useIsomorphicLayoutEffect for the initial check, ensuring it happens after hydration completes

that said, you can try using this as a workaround for now :

function useSSRMediaQuery(query: string, defaultValue: boolean) {
  const [mounted, setMounted] = useState(false)
  const result = useMediaQuery(query, { defaultValue, initializeWithValue: false })
  
  useEffect(() => setMounted(true), [])
  
  return mounted ? result : defaultValue
}

this might give you the behavior that you want?

[quantizor]

a potential solution could be to add a delayEvaluation option that postpones the media query check until after the component has fully mounted

This probably should be the default for the isomorphic effect or you're pretty much guaranteed to get a hydration mismatch

[aquaticcalf]

agree 🤔👍