useMediaQuery

The useMediaQuery hook provides reactive media query matching using React's useSyncExternalStore for optimal SSR support and performance.

Usage

import { useMediaQuery } from '@/hooks';

function ResponsiveComponent() {
  const isMobile = useMediaQuery('(max-width: 768px)');
  const isTablet = useMediaQuery('(min-width: 769px) and (max-width: 1024px)');
  const isDarkMode = useMediaQuery('(prefers-color-scheme: dark)');

  return (
    <div>
      {isMobile && <MobileLayout />}
      {isTablet && <TabletLayout />}
      {!isMobile && !isTablet && <DesktopLayout />}
    </div>
  );
}

API

function useMediaQuery(query: string): boolean

Parameters

Parameter	Type	Description
query	string	A valid CSS media query string

Returns

boolean - Whether the media query currently matches.

SSR Behavior

On the server, the hook returns false by default. This prevents hydration mismatches while ensuring a consistent initial render.

Common Media Queries

// Breakpoints matching design system
const isMobile = useMediaQuery('(max-width: 639px)');
const isTablet = useMediaQuery('(min-width: 640px) and (max-width: 1023px)');
const isDesktop = useMediaQuery('(min-width: 1024px)');

// Accessibility
const reducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
const highContrast = useMediaQuery('(prefers-contrast: high)');

// Device features
const isTouch = useMediaQuery('(hover: none)');
const isRetina = useMediaQuery('(min-resolution: 2dppx)');