All hooks / Viewport and media

useMediaQuery

126 B minified and brotliedSourceMarkdown✓ Works in all modern browsers

Tracks whether a CSS media query matches, and re-renders when it changes.

Renders serverValue on the server and during hydration, then switches to the real value with no hydration mismatch. Concurrent-safe: every component reads the same value in one render.

Import

import { useMediaQuery } from '@vincent.ri/react-tils'
// or only this hook
import { useMediaQuery } from '@vincent.ri/react-tils/useMediaQuery'

Usage

const isWide = useMediaQuery('(min-width: 768px)')
const prefersDark = useMediaQuery('(prefers-color-scheme: dark)')
// Mobile-first site: assume narrow on the server.
const isDesktop = useMediaQuery('(min-width: 1024px)', false)

Live demo

When to use it

JS logic depends on viewport size, prefers-color-scheme, prefers-reduced-motion, pointer type, or orientation.

When not to

Only styling changes. Use a CSS @media rule instead, which needs no JS and never flashes.

API

function useMediaQuery(query: string, serverValue?: boolean): boolean

Coming from another library?

Other libraries call this useMedia, useBreakpoint, useResponsive.