react-media

What is react-media?

The react-media package is a versatile tool for handling CSS media queries in React applications. It allows developers to conditionally render components based on the current viewport size or other media query conditions, making it easier to create responsive designs.

What are react-media's main functionalities?

Basic Media Query

This feature allows you to render different components based on the viewport width. In this example, it displays 'Small Screen' if the viewport width is 599px or less, and 'Large Screen' otherwise.

```jsx
import React from 'react';
import Media from 'react-media';

const App = () => (
  <Media query="(max-width: 599px)">
    {matches => matches ? <p>Small Screen</p> : <p>Large Screen</p>}
  </Media>
);

export default App;
```

Multiple Media Queries

This feature allows you to handle multiple media queries at once. The example demonstrates how to render different components for small, medium, and large screens based on the viewport width.

```jsx
import React from 'react';
import Media from 'react-media';

const App = () => (
  <Media queries={{ small: "(max-width: 599px)", medium: "(min-width: 600px) and (max-width: 1199px)", large: "(min-width: 1200px)" }}>
    {matches => (
      <div>
        {matches.small && <p>Small Screen</p>}
        {matches.medium && <p>Medium Screen</p>}
        {matches.large && <p>Large Screen</p>}
      </div>
    )}
  </Media>
);

export default App;
```

Server-Side Rendering

This feature supports server-side rendering by providing a `defaultMatches` prop. This ensures that the component renders correctly on the server before the client-side JavaScript takes over.

```jsx
import React from 'react';
import Media from 'react-media';

const App = () => (
  <Media query="(max-width: 599px)" defaultMatches={true}>
    {matches => matches ? <p>Small Screen</p> : <p>Large Screen</p>}
  </Media>
);

export default App;
```

Other packages similar to react-media

react-responsive

react-responsive is another popular package for handling media queries in React. It offers a similar API to react-media but includes additional features like support for device orientation and more complex media queries. It is also well-documented and widely used in the React community.

use-media

use-media is a React hook for media queries. It provides a more modern approach by leveraging React hooks, making it a good choice for functional components. It is lightweight and easy to use, but may not be as feature-rich as react-media.

react-responsive-hooks

react-responsive-hooks is another hook-based solution for media queries in React. It offers a simple API and is designed to work seamlessly with functional components. It is similar to use-media but provides additional utilities for handling responsive design.

README

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

queries

Render a <Media> component with a queries prop whose value is an object, where each value is a valid CSS media query. The children prop should be a function whose argument will be an object with the same keys as your queries object, and whose values are booleans indicating whether each query matches.

import React, { Fragment } from 'react';
import Media from 'react-media';

class App extends React.Component {
  render() {
    return (
      <div>
        <Media queries={{
          small: "(max-width: 599px)",
          medium: "(min-width: 600px) and (max-width: 1199px)",
          large: "(min-width: 1200px)"
        }}>
          {matches => (
            <Fragment>
              {matches.small && <p>I am small!</p>}
              {matches.medium && <p>I am medium!</p>}
              {matches.large && <p>I am large!</p>}
            </Fragment>
          )}
        </Media>
      </div>
    );
  }
}

query

Alternatively, if you only need to match against a single media query, the query prop provides a less-verbose approach. More documentation about the difference betwen query and queries can be found below.

import React, { Fragment } from 'react';
import Media from 'react-media';

class App extends React.Component {
  render() {
    return (
      <div>
        <Media query="(max-width: 599px)" render={() =>
          (
            <p>I am small!</p>
          )}
        />
      </div>
    );
  }
}

query vs queries

The queries prop was added to allow for multiple media queries to be matched without excessive nesting or other workarounds. The query prop was retained out of recognition that a single query covers many use cases, and there is already a lot of usage that would be a pain to migrate.

The salient points:

• You cannot use them together: if you do, the component will throw an error. This is to avoid confusion around precedence.
• The render methods differ slightly: for the queries prop, the render and child JSX methods will render if at least one of the given queries is matched. The query prop renders if the given query matches.

queries

In addition to passing a valid media query string, the queries prop will also accept an object of objects whose forms are 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 queries={{ small: { maxWidth: 599 } }}>
          {matches =>
            matches.small ? (
              <p>The document is less than 600px wide.</p>
            ) : (
              <p>The document is at least 600px wide.</p>
            )
          }
        </Media>

        <Media queries={{ small: "(max-width: 599px)" }}>
          {matches =>
            matches.small ? (
              <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.

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 at least one of the queries matches. This is a nice shorthand if you only want to render something for a matching query.	<Media queries={{ foo: ... }} render={() => <p>I matched!</p>} />
children (function)	Receives an object of booleans whose keys are the same as the queries prop, indicating whether each media query matched. Use this prop if you need to render different output for each of specified queries.	<Media queries={{ foo: ... }}>{matches => matches.foo ? <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 at least one of the queries matches. This method serves the same purpose as the render prop, however, you'll create component instances regardless of whether the queries match or not. Hence, using the render prop is preferred (more info).	<Media queries={{ ... }}><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.

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>

onChange

You can specify an optional onChange prop, which is a callback function that will be invoked when the status of the media queries 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={{ small: "(max-width: 599px)" }}
          onChange={matches =>
            matches.small
              ? 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
    queries={{ medium: "(max-width: 500px)" }}
    defaultMatches={{ medium: state.device === 'mobile' }}
    render={() => <Text>Render me below medium breakpoint.</Text>}
  />

  <Media
    queries={{ medium: "(min-width: 501px)" }}
    defaultMatches={{ medium: state.device === 'desktop' }}
    render={() => <Text>Render me above medium breakpoint.</Text>}
  />
</div>;

targetWindow

An optional targetWindow prop can be specified if you want the queries 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!