Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Start rewriting docs towards queries #119

Merged
merged 6 commits into from
Mar 28, 2019
Merged

Start rewriting docs towards queries #119

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
074b7a0
Start rewriting docs towards
tstirrat15 Jan 3, 2019
bbf9c69
Additional modifications towards queries
tstirrat15 Jan 3, 2019
aa03357
Remove incorrect react-responsive comparison
Mar 17, 2019
9c90c94
Merge pull request #124 from contra/patch-1
edorivai Mar 17, 2019
557aaad
Merge branch 'master' into 118-add-queries-block
tstirrat15 Mar 26, 2019
a832017
Add alternative usage in getting started, add section on differences,…
tstirrat15 Mar 26, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
138 changes: 119 additions & 19 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,87 @@ 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](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries). The `children` prop should be a function whose only argument will be a boolean flag that indicates whether the media query matches or not.
### queries

Render a `<Media>` component with a `queries` prop whose value is an object,
where each value is a valid
[CSS media query](https://developer.mozilla.org/en-US/docs/Web/CSS/Media_Queries).
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.

```jsx
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.

```jsx
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](https://facebook.github.io/react/tips/inline-styles.html)
in e.g. `<div style>`. These objects are converted to CSS
media queries via [json2mq](https://github.com/akiran/json2mq/blob/master/README.md#usage).

```jsx
import React from 'react';
Expand All @@ -45,9 +125,21 @@ class App extends React.Component {
render() {
return (
<div>
<Media query="(max-width: 599px)">
<h1>These two Media components are equivalent</h1>

<Media queries={{ small: { maxWidth: 599 } }}>
{matches =>
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>
Expand All @@ -60,15 +152,17 @@ class App extends React.Component {
}
```

## Render props
Keys of media query objects are camel-cased and numeric values automatically get the `px` suffix. See the [json2mq docs](https://github.com/akiran/json2mq/blob/master/README.md#usage) 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](https://github.com/ReactTraining/react-media/issues/70#issuecomment-347774260)).|`<Media query="..."><p>I matched!</p></Media>`|
|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](https://github.com/ReactTraining/react-media/issues/70#issuecomment-347774260)).|`<Media queries={{ ... }}><p>I matched!</p></Media>`|

## `query`

Expand Down Expand Up @@ -111,9 +205,19 @@ class App extends React.Component {

Keys of media query objects are camel-cased and numeric values automatically get the `px` suffix. See the [json2mq docs](https://github.com/akiran/json2mq/blob/master/README.md#usage) 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](https://github.com/ReactTraining/react-media/issues/70#issuecomment-347774260)).|`<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 query changes. This can be useful for triggering side effects, independent of the render lifecycle.
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.

```jsx
import React from 'react';
Expand All @@ -124,9 +228,9 @@ class App extends React.Component {
return (
<div>
<Media
query="(max-width: 599px)"
query={{ small: "(max-width: 599px)" }}
onChange={matches =>
matches
matches.small
? alert('The document is less than 600px wide.')
: alert('The document is at least 600px wide.')
}
Expand All @@ -150,26 +254,22 @@ initialState = {

<div>
<Media
query="(max-width: 500px)"
defaultMatches={state.device === 'mobile'}
queries={{ medium: "(max-width: 500px)" }}
defaultMatches={{ medium: state.device === 'mobile' }}
render={() => <Text>Render me below medium breakpoint.</Text>}
/>

<Media
query="(min-width: 501px)"
defaultMatches={state.device === 'desktop'}
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 `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](https://hackernoon.com/using-a-react-16-portal-to-do-something-cool-2a2d627b0202). See [this PR thread](https://github.com/ReactTraining/react-media/pull/78) for context.

## Compared to react-responsive

If you're curious about how react-media differs from [react-responsive](https://github.com/contra/react-responsive), please see [this comment](https://github.com/ReactTraining/react-media/issues/70#issuecomment-347774260).
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](https://hackernoon.com/using-a-react-16-portal-to-do-something-cool-2a2d627b0202). See [this PR thread](https://github.com/ReactTraining/react-media/pull/78) for context.

## About

Expand Down