react-media
react-media
is a CSS media query component for React.
A <Media>
component listens for matches to a CSS media query and renders stuff based on whether the query matches or not.
Installation
Using npm:
$ npm install --save react-media
Then, use as you would anything else:
// using ES modules
import Media from 'react-media';
// using CommonJS modules
var Media = require('react-media');
The UMD build is also available on unpkg:
<script src="https://unpkg.com/react-media"></script>
You can find the library on window.ReactMedia
.
Basic usage
Render a <Media>
component with a query
prop whose value is a valid CSS media query. The children
prop should be a function whose only argument will be a boolean flag that indicates whether the media query matches or not.
import React from 'react';
import Media from 'react-media';
class App extends React.Component {
render() {
return (
<div>
<Media query="(max-width: 599px)">
{matches =>
matches ? (
<p>The document is less than 600px wide.</p>
) : (
<p>The document is at least 600px wide.</p>
)
}
</Media>
</div>
);
}
}
Render props
There are three props which allow you to render your content. They each serve a subtly different purpose.
prop | description | example |
---|---|---|
render | Only invoked when the query matches. This is a nice shorthand if you only want to render something for a matching query. | <Media query="..." render={() => <p>I matched!</p>} /> |
children (function) | Receives a single boolean element, indicating whether the media query matched. Use this prop if you need to render something when the query doesn't match. | <Media query="...">{matches => matches ? <p>I matched!</p> : <p>I didn't match</p>}</Media> |
children (react element) | If you render a regular React element within <Media> , it will render that element when the query matches. This method serves the same purpose as the render prop, however, you'll create component instances regardless of whether the query matches or not. Hence, using the render prop is preferred (more info). |
<Media query="..."><p>I matched!</p></Media> |
query
In addition to passing a valid media query string, the query
prop will also accept an object, similar to React's built-in support for inline style objects in e.g. <div style>
. These objects are converted to CSS media queries via json2mq.
import React from 'react';
import Media from 'react-media';
class App extends React.Component {
render() {
return (
<div>
<h1>These two Media components are equivalent</h1>
<Media query={{ maxWidth: 599 }}>
{matches =>
matches ? (
<p>The document is less than 600px wide.</p>
) : (
<p>The document is at least 600px wide.</p>
)
}
</Media>
<Media query="(max-width: 599px)">
{matches =>
matches ? (
<p>The document is less than 600px wide.</p>
) : (
<p>The document is at least 600px wide.</p>
)
}
</Media>
</div>
);
}
}
Keys of media query objects are camel-cased and numeric values automatically get the px
suffix. See the json2mq docs for more examples of queries you can construct using objects.
onChange
You can specify an optional onChange
prop, which is a callback function that will be invoked when the status of the media query changes. This can be useful for triggering side effects, independent of the render lifecycle.
import React from 'react';
import Media from 'react-media';
class App extends React.Component {
render() {
return (
<div>
<Media
query="(max-width: 599px)"
onChange={matches =>
matches
? alert('The document is less than 600px wide.')
: alert('The document is at least 600px wide.')
}
/>
</div>
);
}
}
Server-side rendering (SSR)
If you render a <Media>
component on the server, it will match by default. You can override the default behavior by setting the defaultMatches
prop.
When rendering on the server you can use the defaultMatches
prop to set the initial state on the server to match whatever you think it will be on the client. You can detect the user's device by analyzing the user-agent string from the HTTP request in your server-side rendering code.
initialState = {
device: 'mobile' // add your own guessing logic here, based on user-agent for example
};
<div>
<Media
query="(max-width: 500px)"
defaultMatches={state.device === 'mobile'}
render={() => <Text>Render me below medium breakpoint.</Text>}
/>
<Media
query="(min-width: 501px)"
defaultMatches={state.device === 'desktop'}
render={() => <Text>Render me above medium breakpoint.</Text>}
/>
</div>;
targetWindow
An optional targetWindow
prop can be specified if you want the query
to be evaluated against a different window object than the one the code is running in. This can be useful if you are rendering part of your component tree to an iframe or a popup window. See this PR thread for context.
About
react-media
is developed and maintained by React Training. If you're interested in learning more about what React can do for your company, please get in touch!