{"id":15194,"library":"react-media","title":"React Media Queries","description":"react-media is a React component that enables declarative CSS media queries directly within React applications, simplifying responsive design. As of version 1.10.0, it offers a stable and widely used API for conditionally rendering components based on various viewport characteristics. While its release cadence is moderate rather than rapid, it has consistently received updates addressing compatibility with newer React versions and introducing key features like enhanced Server-Side Rendering (SSR) support via the `defaultMatches` prop and improved iframe integration with the `targetWindow` prop. It distinguishes itself by providing a clean, component-based abstraction over the native `window.matchMedia` API, allowing developers to focus on component logic rather than direct DOM API interaction.","status":"active","version":"1.10.0","language":"javascript","source_language":"en","source_url":"https://github.com/ReactTraining/react-media","tags":["javascript","react","media","media query","query","css","responsive","typescript"],"install":[{"cmd":"npm install react-media","lang":"bash","label":"npm"},{"cmd":"yarn add react-media","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-media","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core peer dependency for any React component library.","package":"react","optional":false}],"imports":[{"note":"The primary component is a named export. Ensure you destructure it correctly.","wrong":"const Media = require('react-media'); // Incorrect for named export\nconst Media = require('react-media').default; // react-media uses named exports","symbol":"Media","correct":"import { Media } from 'react-media';"},{"note":"For functional components, the `useMedia` hook provides similar functionality to the `Media` component but as a hook.","symbol":"useMedia","correct":"import { useMedia } from 'react-media';"},{"note":"TypeScript users can import specific types for props or render functions for better type safety.","symbol":"Media type","correct":"import type { MediaRenderProps } from 'react-media';"}],"quickstart":{"code":"import React from 'react';\nimport { Media } from 'react-media';\n\ninterface MyResponsiveComponentProps {\n  children: React.ReactNode;\n}\n\nconst MyResponsiveComponent: React.FC<MyResponsiveComponentProps> = ({ children }) => {\n  return (\n    <Media queries={{\n      small: '(max-width: 599px)',\n      medium: '(min-width: 600px) and (max-width: 1199px)',\n      large: '(min-width: 1200px)',\n      print: 'print'\n    }}>\n      {matches => (\n        <div style={{ padding: '20px', border: '1px solid #ccc' }}>\n          {matches.small && <p>You are on a small screen or mobile device.</p>}\n          {matches.medium && <p>You are on a tablet or medium-sized screen.</p>}\n          {matches.large && <p>You are on a desktop or large screen.</p>}\n          {matches.print && <p>Preparing for print!</p>}\n          {!matches.small && !matches.medium && !matches.large && !matches.print && (\n            <p>No specific media query matched (perhaps a server-side render without defaultMatches).</p>\n          )}\n          {children}\n        </div>\n      )}\n    </Media>\n  );\n};\n\nexport default MyResponsiveComponent;","lang":"typescript","description":"This quickstart demonstrates how to use the <Media> component to render different content based on predefined CSS media queries, including handling print media."},"warnings":[{"fix":"Upgrade `react-media` to version 1.6.0 or higher to ensure compatibility with modern React versions (>=15.5) and resolve `React.PropTypes` warnings.","message":"Prior to v1.6.0, `react-media` used `React.PropTypes`. This was deprecated in React 15.5. Version 1.6.0 switched to the standalone `prop-types` package.","severity":"breaking","affected_versions":"<1.6.0"},{"fix":"Use the `<Media defaultMatches={{ queryName: true }}` prop to provide initial match values for the server render. For example, `<Media queries={{ mobile: '(max-width: 768px)' }} defaultMatches={{ mobile: false }}>`.","message":"When using `react-media` with Server-Side Rendering (SSR), the initial render on the server does not have access to the `window` object, leading to `matches` being `false` for all queries. This can cause hydration mismatches.","severity":"gotcha","affected_versions":"All versions"},{"fix":"As of v1.8.0, use the `<Media targetWindow={iframeRef.current.contentWindow}>` prop to explicitly specify which window context the media queries should be evaluated against.","message":"For applications embedded within iframes, media queries are resolved against the parent window by default, which might not be the desired behavior.","severity":"gotcha","affected_versions":"All versions <1.8.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Update `react-media` to version 1.6.0 or newer: `npm install react-media@latest` or `yarn add react-media@latest`.","cause":"Using an older version of `react-media` (prior to 1.6.0) with a React version that has deprecated `React.PropTypes` (React 15.5 and above).","error":"Warning: Accessing PropTypes via React.PropTypes is deprecated. Use the 'prop-types' package directly."},{"fix":"Provide initial values for media queries on the server using the `defaultMatches` prop: `<Media queries={{ mobile: '(max-width: 768px)' }} defaultMatches={{ mobile: false }}>`.","cause":"This hydration mismatch warning occurs during SSR because `react-media` cannot determine media query matches on the server without a `window` object, leading to a discrepancy between server-rendered and client-rendered HTML.","error":"Warning: Prop `%s` did not match. Server: `%s` Client: `%s`"},{"fix":"Ensure you are either conditionally rendering `react-media` only on the client or, more commonly, provide `defaultMatches` for SSR scenarios as described in the hydration mismatch warning. Alternatively, implement a mock `window` object for server-side testing if necessary.","cause":"This error typically happens during Server-Side Rendering (SSR) when `react-media` attempts to access `window.matchMedia` in a server environment where `window` is undefined.","error":"TypeError: Cannot read properties of undefined (reading 'matchMedia')"}],"ecosystem":"npm"}