React useMediaQuery Hook

Ever tried to build responsive components in React and ended up with window.innerWidth checks, resize event listeners, and broken SSR? You know the drill—manually tracking screen sizes, dealing with hydration mismatches, forgetting to clean up event listeners. This free open source React useMediaQuery custom hook handles all that responsive complexity so you can focus on building adaptive UIs instead of reinventing media query logic in your React applications.

useMediaQuery showcase

Real-time responsive design with automatic breakpoint tracking:

"use client";import * as React from "react";import { Badge } from "@/components/ui/badge";import { Label } from "@/components/ui/label";import { useMediaQuery } from "@/components/ui/shadcn-io/use-media-query";export default function UseMediaQueryDemo() {  const isMobile = useMediaQuery("(max-width: 768px)");  const isDarkMode = useMediaQuery("(prefers-color-scheme: dark)");  return (    <div className="p-6 max-w-sm mx-auto space-y-6">      {/* Header */}      <div className="text-center space-y-2">        <h3 className="text-lg font-semibold">Media Query Demo</h3>        <p className="text-sm text-muted-foreground">Responsive breakpoint detection</p>      </div>            {/* Screen Size */}      <div className="space-y-2">        <Label className="text-sm font-medium">Screen Size</Label>        <div className="bg-muted rounded p-3 min-h-[48px] flex items-center justify-center">          <Badge variant={isMobile ? "default" : "secondary"} className="text-lg px-4 py-2">            {isMobile ? "📱 Mobile" : "🖥️ Desktop"}          </Badge>        </div>      </div>      {/* Theme Preference */}      <div className="space-y-2">        <Label className="text-sm font-medium">Theme Preference</Label>        <div className="bg-muted rounded p-3 min-h-[48px] flex items-center justify-center">          <Badge variant={isDarkMode ? "default" : "secondary"} className="text-lg px-4 py-2">            {isDarkMode ? "🌙 Dark" : "☀️ Light"}          </Badge>        </div>      </div>      {/* Current State */}      <div className="space-y-2">        <Label className="text-sm font-medium">Query States</Label>        <div className="bg-muted rounded p-2 min-h-[40px] flex items-center justify-center">          <div className="flex gap-2">            <Badge variant="outline" className="text-xs">              Mobile: {isMobile ? "✓" : "✗"}            </Badge>            <Badge variant="outline" className="text-xs">              Dark: {isDarkMode ? "✓" : "✗"}            </Badge>          </div>        </div>      </div>      {/* Instructions */}      <div className="text-center min-h-[20px] flex items-center justify-center">        <div className="text-xs text-muted-foreground">          Resize window or change system theme to see updates        </div>      </div>    </div>  );}

"use client"import { useState } from "react"import { useIsomorphicLayoutEffect } from "@/components/ui/kibo-ui/use-isomorphic-layout-effect"type UseMediaQueryOptions = {  defaultValue?: boolean  initializeWithValue?: boolean}const IS_SERVER = typeof window === "undefined"export function useMediaQuery(  query: string,  {    defaultValue = false,    initializeWithValue = true,  }: UseMediaQueryOptions = {},): boolean {  const getMatches = (query: string): boolean => {    if (IS_SERVER) {      return defaultValue    }    return window.matchMedia(query).matches  }  const [matches, setMatches] = useState<boolean>(() => {    if (initializeWithValue) {      return getMatches(query)    }    return defaultValue  })  // Handles the change event of the media query.  function handleChange() {    setMatches(getMatches(query))  }  useIsomorphicLayoutEffect(() => {    const matchMedia = window.matchMedia(query)    // Triggered at the first client-side load and if query changes    handleChange()    // Use deprecated `addListener` and `removeListener` to support Safari < 14 (#135)    if (matchMedia.addListener) {      matchMedia.addListener(handleChange)    } else {      matchMedia.addEventListener("change", handleChange)    }    return () => {      if (matchMedia.removeListener) {        matchMedia.removeListener(handleChange)      } else {        matchMedia.removeEventListener("change", handleChange)      }    }  }, [query])  return matches}export type { UseMediaQueryOptions }

This free open source React hook simplifies responsive design with TypeScript support for modern JavaScript applications. Whether you're building mobile-first layouts, dark mode detection, or accessibility features in your Next.js projects, this React hook keeps your media queries reactive.

Installation

npx shadcn@latest add https://www.shadcn.io/registry/use-media-query.json

npx shadcn@latest add https://www.shadcn.io/registry/use-media-query.json

pnpm dlx shadcn@latest add https://www.shadcn.io/registry/use-media-query.json

bunx shadcn@latest add https://www.shadcn.io/registry/use-media-query.json

Why most media query implementations suck

Look, you could keep writing window.innerWidth checks and resize event listeners. But then you hit the responsive web complexity—server-side rendering issues, event cleanup headaches, inconsistent breakpoint logic across components in React applications.

Most developers manually track window dimensions with resize listeners that fire constantly, causing performance issues in TypeScript components. Or they create custom breakpoint logic that doesn't match CSS media queries, leading to inconsistent responsive behavior. Some forget about event cleanup and wonder why their resize handlers accumulate over time in Next.js projects.

This React hook uses the native matchMedia API under the hood, which is specifically designed for efficient media query tracking in JavaScript applications. The browser handles all the optimization, plus you get real-time updates when queries change.

Plus it handles all the edge cases—SSR compatibility, automatic event cleanup, Safari fallbacks for older versions in React development. No more scattered resize listeners or hydration errors.

This free open source React hook manages responsive state while you focus on building features. Whether you're creating React applications, Next.js sites, or TypeScript components, reliable media query detection keeps your JavaScript development adaptive.

Features

• Responsive design with automatic breakpoint tracking and screen size detection in React applications
• User preferences detect dark mode, reduced motion, and accessibility settings in TypeScript components
• Real-time updates automatically updates when media query state changes in Next.js projects
• SSR compatible with optional initialization for server-side rendering in JavaScript development
• Safari support uses deprecated listeners for Safari < 14 compatibility in React frameworks
• Type safety with full TypeScript support and proper return types for modern applications
• Free open source designed for modern React development workflows

When you'll actually use this

Real talk—this isn't for every responsive need in React applications. CSS media queries handle most styling cases perfectly. But when you need responsive logic in your React components or JavaScript behavior, this React hook delivers in Next.js projects.

Perfect for:

• Responsive components - Show/hide components based on screen size built with TypeScript
• User preferences - Detect dark mode, reduced motion, or high contrast settings using React patterns
• Navigation patterns - Mobile hamburger menus vs desktop navigation bars in JavaScript applications
• Conditional rendering - Different layouts for mobile vs desktop experiences in React components
• Accessibility features - Adapt behavior based on user motion preferences in Next.js applications
• Device detection - Portrait/landscape orientation and touch capability using TypeScript safety

API Reference

useMediaQuery

useMediaQuery(query: string, options?: UseMediaQueryOptions): boolean

UseMediaQueryOptions

Return Value

Returns a boolean indicating whether the media query currently matches.

Common gotchas

SSR requires careful initialization: Use initializeWithValue: false for SSR to prevent hydration mismatches in React applications. The React hook will start with your default value and update after client hydration.

Media queries are case-sensitive: Make sure your query syntax is correct in TypeScript components. Invalid queries will always return false without throwing errors.

Performance is generally excellent: The matchMedia API is optimized by browsers in Next.js projects, but avoid creating too many concurrent media query listeners for complex responsive logic.

Mobile browsers handle orientation changes: Orientation queries update automatically in JavaScript applications, but there might be a small delay during device rotation.

Browser compatibility varies: Some media query features aren't supported in older browsers in React frameworks. Always test your responsive logic across different devices.

Timing considerations: Media query changes are asynchronous and may not update immediately in TypeScript projects. Handle loading states appropriately for better user experience.

Related hooks you will also like

Questions you might have