Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Media
✓ import { Media } from 'react-media';
✗ const Media = require('react-media'); // Incorrect for named export
const Media = require('react-media').default; // react-media uses named exports
The primary component is a named export. Ensure you destructure it correctly.
useMedia
✓ import { useMedia } from 'react-media';
For functional components, the `useMedia` hook provides similar functionality to the `Media` component but as a hook.
Media type
✓ import type { MediaRenderProps } from 'react-media';
TypeScript users can import specific types for props or render functions for better type safety.
This quickstart demonstrates how to use the <Media> component to render different content based on predefined CSS media queries, including handling print media.
import React from 'react';
import { Media } from 'react-media';
interface MyResponsiveComponentProps {
children: React.ReactNode;
}
const MyResponsiveComponent: React.FC<MyResponsiveComponentProps> = ({ children }) => {
return (
<Media queries={{
small: '(max-width: 599px)',
medium: '(min-width: 600px) and (max-width: 1199px)',
large: '(min-width: 1200px)',
print: 'print'
}}>
{matches => (
<div style={{ padding: '20px', border: '1px solid #ccc' }}>
{matches.small && <p>You are on a small screen or mobile device.</p>}
{matches.medium && <p>You are on a tablet or medium-sized screen.</p>}
{matches.large && <p>You are on a desktop or large screen.</p>}
{matches.print && <p>Preparing for print!</p>}
{!matches.small && !matches.medium && !matches.large && !matches.print && (
<p>No specific media query matched (perhaps a server-side render without defaultMatches).</p>
)}
{children}
</div>
)}
</Media>
);
};
export default MyResponsiveComponent;
Debug
Known issues
breakingPrior 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.fixUpgrade `react-media` to version 1.6.0 or higher to ensure compatibility with modern React versions (>=15.5) and resolve `React.PropTypes` warnings.
affects: <1.6.0
gotchaWhen 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.fixUse 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 }}>`. affects: All versions
gotchaFor applications embedded within iframes, media queries are resolved against the parent window by default, which might not be the desired behavior.fixAs 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. affects: All versions <1.8.0
Errors
Common errors & fixes
Warning: Accessing PropTypes via React.PropTypes is deprecated. Use the 'prop-types' package directly.
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).
fixUpdate `react-media` to version 1.6.0 or newer: `npm install react-media@latest` or `yarn add react-media@latest`.
Warning: Prop `%s` did not match. Server: `%s` Client: `%s`
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.
fixProvide initial values for media queries on the server using the `defaultMatches` prop: `<Media queries={{ mobile: '(max-width: 768px)' }} defaultMatches={{ mobile: false }}>`. TypeError: Cannot read properties of undefined (reading 'matchMedia')
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.
fixEnsure 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.
Audit
Dependencies
reactrequiredCore peer dependency for any React component library.