Skip to content

Add docs for new Context API #665

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

Closed
wants to merge 10 commits into from
Closed

Add docs for new Context API #665

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
566406e
Add docs for new Context API (R16.3)
alexkrolick Mar 6, 2018
0780f72
Reorganize examples & legacy docs
alexkrolick Mar 21, 2018
a5022da
Add in-page TOC
alexkrolick Mar 21, 2018
fe3d0a4
Typo
alexkrolick Mar 21, 2018
808e5bd
Rephrase and reorganize
alexkrolick Mar 21, 2018
de22379
Syntax tweaks
alexkrolick Mar 21, 2018
291b2fd
Wording tweaks
alexkrolick Mar 21, 2018
6aa1995
Add solution to motivation problem
alexkrolick Mar 21, 2018
7c6688c
Highlight createContext()
alexkrolick Mar 21, 2018
b49f99b
Highlight whole createContext() call
alexkrolick Mar 21, 2018
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
241 changes: 71 additions & 170 deletions content/docs/context.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,39 +4,83 @@ title: Context
permalink: docs/context.html
---

> Note:
>
> `React.PropTypes` has moved into a different package since React v15.5. Please use [the `prop-types` library instead](https://www.npmjs.com/package/prop-types) to define `contextTypes`.
>
>We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) to automate the conversion.
Context provides a way to pass data through the component tree without having to pass props down manually at every level.

- [API](#api)
- [React.createContext](#reactcreatecontext)
- [Provider](#provider)
- [Consumer](#consumer)
- [Examples](#examples)
- [Static Context](#static-context)
- [Dynamic Context](#dynamic-context)
- [Motivation](#motivation)
- [Legacy API](#legacy-api)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like this table of contents 👍


## API

### `React.createContext`

```js
const {Provider, Consumer} = React.createContext([default]);
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why [default] ? (Why the array syntax?) Suggestion:

const {Provider, Consumer} = React.createContext(defaultValue);

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was thinking [] indicated optional arguments. Replacing it with a text note is fine; it's not a real type signature or anything.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gotcha. I don't think thats' what "[]" implies to me. 👍

```

Creates a `{ Provider, Consumer }` pair.

Takes one argument, the default context that Consumers will receive when they don't have a matching Provider.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:

Accepts an optional default value to be passed to Consumers without a Provider ancestor.



### `Provider`

With React, it's easy to track the flow of data through your React components. When you look at a component, you can see which props are being passed, which makes your apps easy to reason about.
```js
<Provider value={/* some value */}>
```

A React component that allows Consumers to subscribe to context changes.

Takes one prop, `value`, which will be passed to the [render prop](/docs/render-props.html) of child Consumers for the matching context anywhere in the component tree. One Provider can be connected to many Consumers.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:

Accepts a value prop to be passed to Consumers that are descendants of this Provider. One Provider can be connected to many Consumers. Providers can be nested to override values deeper within the tree.


### `Consumer`

```js
<Consumer>
{ value => { /* render something based on the context value */ } }
</Consumer>
```

In some cases, you want to pass data through the component tree without having to pass the props down manually at every level.
You can do this directly in React with the powerful "context" API.
A React component that subscribes to context changes.

Takes a function as the `children` prop that receives the `value` prop of the matching Provider. This function will be called whenever the Provider's value is updated.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion:

Requires a function as a child. This function receives the current context value and returns a React node. This function will be called whenever the Provider's value is updated.


> Note:
>
> A [new, safe version of context](https://github.com/reactjs/rfcs/blob/master/text/0002-new-version-of-context.md) is under development for the upcoming 16.3 release.
> For more information about this pattern, see [render props](/docs/render-props.html).

## Examples

### Static Context

Here is an example illustrating how you might inject a "theme" using context:

## Why Not To Use Context
`embed:context/theme-example.js`

The vast majority of applications do not need to use context.
### Dynamic Context

If you want your application to be stable, don't use context. It is an experimental API and it is likely to break in future releases of React.
A more complex example with dynamic values for the theme:

If you aren't familiar with state management libraries like [Redux](https://github.com/reactjs/redux) or [MobX](https://github.com/mobxjs/mobx), don't use context. For many practical applications, these libraries and their React bindings are a good choice for managing state that is relevant to many components. It is far more likely that Redux is the right solution to your problem than that context is the right solution.
**theme-contex.js**
`embed:context/theme-detailed-theme-context.js`

If you're still learning React, don't use context. There is usually a better way to implement functionality just using props and state.
**themed-button.js**
`embed:context/theme-detailed-themed-button.js`

If you insist on using context despite these warnings, try to isolate your use of context to a small area and avoid using the context API directly when possible so that it's easier to upgrade when the API changes.
**app.js**
`embed:context/theme-detailed-app.js`

## How To Use Context
## Motivation

Suppose you have a structure like:
Context is designed to relieve the pain of passing props down through a deeply nested component tree. For example, in the code below we manually thread through a color prop in order to style the Button and Message components. Using context, we can avoid passing props through intermediate elements.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm still not a fan of this sequencing. We show motivation after we show usage examples. That feels backwards to me. I think it would be better to present a problem, and then how to solve it using Context. Step by step.


```javascript
```js
class Button extends React.Component {
render() {
return (
Expand All @@ -51,6 +95,11 @@ class Message extends React.Component {
render() {
return (
<div>
{/*
The Message component must take `color` as as prop to pass it to the
Button. Using context, the Button could connect to the color context
on its own.
*/}
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This block comment within JSX does not read very well. Move it into the render function as just inline comments?

{this.props.text} <Button color={this.props.color}>Delete</Button>
</div>
);
Expand All @@ -68,156 +117,8 @@ class MessageList extends React.Component {
}
```

In this example, we manually thread through a `color` prop in order to style the `Button` and `Message` components appropriately. Using context, we can pass this through the tree automatically:

```javascript{6,13-15,21,28-30,40-42}
import PropTypes from 'prop-types';

class Button extends React.Component {
render() {
return (
<button style={{background: this.context.color}}>
{this.props.children}
</button>
);
}
}

Button.contextTypes = {
color: PropTypes.string
};

class Message extends React.Component {
render() {
return (
<div>
{this.props.text} <Button>Delete</Button>
</div>
);
}
}

class MessageList extends React.Component {
getChildContext() {
return {color: "purple"};
}

render() {
const children = this.props.messages.map((message) =>
<Message text={message.text} />
);
return <div>{children}</div>;
}
}

MessageList.childContextTypes = {
color: PropTypes.string
};
```

By adding `childContextTypes` and `getChildContext` to `MessageList` (the context provider), React passes the information down automatically and any component in the subtree (in this case, `Button`) can access it by defining `contextTypes`.

If `contextTypes` is not defined, then `context` will be an empty object.

## Parent-Child Coupling

Context can also let you build an API where parents and children communicate. For example, one library that works this way is [React Router V4](https://reacttraining.com/react-router):

```javascript
import { BrowserRouter as Router, Route, Link } from 'react-router-dom';

const BasicExample = () => (
<Router>
<div>
<ul>
<li><Link to="/">Home</Link></li>
<li><Link to="/about">About</Link></li>
<li><Link to="/topics">Topics</Link></li>
</ul>

<hr />

<Route exact path="/" component={Home} />
<Route path="/about" component={About} />
<Route path="/topics" component={Topics} />
</div>
</Router>
);
```

By passing down some information from the `Router` component, each `Link` and `Route` can communicate back to the containing `Router`.

Before you build components with an API similar to this, consider if there are cleaner alternatives. For example, you can pass entire React components as props if you'd like to.

## Referencing Context in Lifecycle Methods

If `contextTypes` is defined within a component, the following [lifecycle methods](/docs/react-component.html#the-component-lifecycle) will receive an additional parameter, the `context` object:

- [`constructor(props, context)`](/docs/react-component.html#constructor)
- [`componentWillReceiveProps(nextProps, nextContext)`](/docs/react-component.html#componentwillreceiveprops)
- [`shouldComponentUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#shouldcomponentupdate)
- [`componentWillUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#componentwillupdate)

> Note:
>
> As of React 16, `componentDidUpdate` no longer receives `prevContext`.

## Referencing Context in Stateless Functional Components

Stateless functional components are also able to reference `context` if `contextTypes` is defined as a property of the function. The following code shows a `Button` component written as a stateless functional component.

```javascript
import PropTypes from 'prop-types';

const Button = ({children}, context) =>
<button style={{background: context.color}}>
{children}
</button>;

Button.contextTypes = {color: PropTypes.string};
```

## Updating Context

Don't do it.

React has an API to update context, but it is fundamentally broken and you should not use it.

The `getChildContext` function will be called when the state or props changes. In order to update data in the context, trigger a local state update with `this.setState`. This will trigger a new context and changes will be received by the children.

```javascript
import PropTypes from 'prop-types';

class MediaQuery extends React.Component {
constructor(props) {
super(props);
this.state = {type:'desktop'};
}

getChildContext() {
return {type: this.state.type};
}

componentDidMount() {
const checkMediaQuery = () => {
const type = window.matchMedia("(min-width: 1025px)").matches ? 'desktop' : 'mobile';
if (type !== this.state.type) {
this.setState({type});
}
};

window.addEventListener('resize', checkMediaQuery);
checkMediaQuery();
}

render() {
return this.props.children;
}
}

MediaQuery.childContextTypes = {
type: PropTypes.string
};
```
## Legacy API

The problem is, if a context value provided by component changes, descendants that use that value won't update if an intermediate parent returns `false` from `shouldComponentUpdate`. This is totally out of control of the components using context, so there's basically no way to reliably update the context. [This blog post](https://medium.com/@mweststrate/how-to-safely-use-react-context-b7e343eff076) has a good explanation of why this is a problem and how you might get around it.
> The legacy context API was deprecated in React 16.3
>
> React previously shipped with an experimental context API. The old API will be supported in all 16.x releases, but applications using it should migrate to the new version. Read the [legacy context docs here](/docs/legacy-context.html).
Loading