useMediaQuery

1"use client"
2 
3import * as React from "react"
4 
5export interface UseMediaQueryOptions {
6  /** Snapshot used during SSR and before hydration. Defaults to false. */
7  serverFallback?: boolean
8}
9 
10/**
11 * Subscribe to a CSS media query and return whether it currently matches.
12 * `useSyncExternalStore` wires `matchMedia`, an external data source, into the
13 * React tree: subscribe attaches the `change` listener of `matchMedia(query)`,
14 * getSnapshot reads `.matches`, and getServerSnapshot returns `serverFallback`
15 * while rendering on the server. All three are new closures whenever `query`
16 * changes, so a changing `query` unsubscribes from the old `matchMedia` and
17 * subscribes to the new one on its own — no hand-written `useEffect`, no
18 * dependency array, and no `setState` in an effect body.
19 *
20 * `useReducedMotion` in this repo's `animated-text.tsx` is this hook specialised
21 * to a single query (`prefers-reduced-motion: reduce`) with `serverFallback`
22 * pinned to `false`.
23 */
24export function useMediaQuery(query: string, options: UseMediaQueryOptions = {}): boolean {
25  const { serverFallback = false } = options
26 
27  const subscribe = React.useCallback(
28    (callback: () => void) => {
29      if (typeof window === "undefined") return () => {}
30      const mql = window.matchMedia(query)
31      mql.addEventListener("change", callback)
32      return () => mql.removeEventListener("change", callback)
33    },
34    [query],
35  )
36 
37  const getSnapshot = React.useCallback(() => window.matchMedia(query).matches, [query])
38  const getServerSnapshot = React.useCallback(() => serverFallback, [serverFallback])
39 
40  return React.useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot)
41}
42 
43export default useMediaQuery