react-responsive

react-responsive lets React apps conditionally render UI based on CSS media queries, without hand-writing window.matchMedia listener boilerplate. It exposes a useMediaQuery hook and a MediaQuery component that both accept either a raw CSS media-query string or a camelCased shorthand object (minWidth, orientation, minResolution, and more), which the library hyphenates and assembles into a valid query internally.

Because window.matchMedia doesn’t exist during server-side rendering, the library also ships a Context provider that lets you inject a fixed device object (e.g. { width: 500 }) so components render deterministically on the server and rehydrate correctly on the client. This makes it a common building block for breakpoint-driven component sets (Desktop, Tablet, Mobile) in Next.js and other SSR React setups.

What You Get

• useMediaQuery hook - subscribe to a media query and get a live boolean matches value that updates on viewport/device changes.
• MediaQuery component - a declarative wrapper that renders children (or a render-prop function) only when the query matches.
• Camel-cased shorthand props - write minWidth={768} instead of hand-authoring (min-width: 768px) media-query syntax.
• SSR-safe device context - pass a fixed device/viewport object through React Context so server-rendered output matches the eventual client render.
• onChange callback support - run side effects whenever a query’s match state flips, on both the hook and component APIs.

Common Use Cases

• Breakpoint-driven component sets - build Desktop/Tablet/Mobile wrapper components once, then reuse them across a whole app.
• Server-side rendering with Next.js - supply device width via ResponsiveContext.Provider so SSR output doesn’t flash-of-wrong-layout on hydration.
• Orientation- and resolution-aware UI - show retina-specific assets or swap layouts on orientation: portrait without custom CSS classes.
• Conditional feature rendering in tests - use the Context provider in component tests to snapshot both mobile and desktop render trees deterministically.

Under The Hood

Architecture The library is organized into small, single-responsibility modules: mediaQuery.ts defines the full set of valid CSS media feature keys as a PropTypes schema, toQuery.ts walks that schema against a settings object to hyphenate keys and assemble a CSS media-query string, useMediaQuery.ts is the core hook that composes several internal hooks (useDevice, useQuery, useMatchMedia, useMatches) to build the query, instantiate a matchmediaquery match instance, and subscribe/unsubscribe a change listener through useEffect, and Component.ts (MediaQuery) is a thin functional wrapper around the hook for children/render-prop consumption, with Context.ts providing the SSR device-injection point. Data flows in one direction — settings/device props or context in, a query string out, a matchMedia instance out of that, a boolean matches state out of that — with no external store beyond the DOM API it wraps.

Tech Stack Written in TypeScript, targeting React 16.8+ as a peer dependency (hooks-only baseline). Runtime dependencies are narrow and purpose-built: matchmediaquery (a matchMedia shim usable outside real browsers), hyphenate-style-name (camelCase-to-kebab-case key conversion), prop-types (runtime validation on the component API), and shallow-equal (avoids redundant state updates when device objects are structurally identical). The build uses Rollup with @rollup/plugin-typescript and rollup-plugin-node-externals to emit separate CJS and ESM bundles, plus an independent tsc --declaration --emitDeclarationOnly pass for type definitions.

Code Quality Dedicated test files cover every core module (Component_test.tsx, mediaQuery_test.ts, toQuery_test.ts, useMediaQuery_test.tsx) using Mocha, chai, and sinon, with a match-media-mock + jsdom setup faking browser matchMedia behavior for deterministic assertions on props, device overrides, context-supplied device, and onChange callbacks. Error handling is explicit where it counts — useMediaQuery throws immediately on an empty/invalid composed query rather than silently no-op’ing. ESLint (with typescript-eslint and eslint-plugin-compat) and Prettier are configured with a combined lint-and-fix script, though no GitHub Actions workflow is present in the repository, so CI enforcement isn’t visible from the source alone.

API Design The public surface is deliberately small: a single default export doubles as the MediaQuery component, alongside named exports for useMediaQuery, toQuery, and Context, so consumers pick whichever surface fits without extra imports. The hook signature accepts either a literal CSS query string or a camelCased shorthand object, removing the need to hand-write media-query syntax, and the component supports both plain children and a render-prop function receiving the boolean match for more advanced conditional layouts. The README documents hook and component usage, SSR guidance via Context, and Next.js dynamic-import guidance in detail, though there’s no separate example project directory beyond the inline README snippets and a typedoc-generated API reference.