Skip to content

Commit dbce488

Browse files
bvaughnbvaughn
authored
Merge pull request #3 from alexkrolick/new-context-api
New context api
2 parents 29d6592 + b49f99b commit dbce488

9 files changed

+468
-182
lines changed

‎content/docs/context.md

+53-181
Original file line numberDiff line numberDiff line change
@@ -4,220 +4,92 @@ title: Context
44
permalink: docs/context.html
55
---
66

7-
> Note:
8-
>
9-
> `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`.
10-
>
11-
>We provide [a codemod script](/blog/2017/04/07/react-v15.5.0.html#migrating-from-react.proptypes) to automate the conversion.
12-
13-
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.
14-
15-
In some cases, you want to pass data through the component tree without having to pass the props down manually at every level.
16-
You can do this directly in React with the powerful "context" API.
17-
18-
> Note:
19-
>
20-
> 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.
7+
Context provides a way to pass data through the component tree without having to pass props down manually at every level.
218

9+
In a typical React application, data is passed top-down (parent to child) via props, but this can be cumbersome for certain types of props (e.g. locale preference, UI theme) that are required by many components within an application. Context provides a way to share values like this between components without having to explicitly pass a prop through every level of the tree.
2210

23-
## Why Not To Use Context
11+
- [Motivation](#motivation)
12+
- [API](#api)
13+
- [React.createContext](#reactcreatecontext)
14+
- [Provider](#provider)
15+
- [Consumer](#consumer)
16+
- [Examples](#examples)
17+
- [Static Context](#static-context)
18+
- [Dynamic Context](#dynamic-context)
19+
- [Legacy API](#legacy-api)
2420

25-
The vast majority of applications do not need to use context.
2621

27-
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.
22+
## Motivation
2823

29-
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.
24+
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:
3025

31-
If you're still learning React, don't use context. There is usually a better way to implement functionality just using props and state.
26+
`embed:context/motivation-problem.js`
3227

33-
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.
28+
Using context, we can avoid passing props through intermediate elements:
3429

35-
## How To Use Context
30+
`embed:context/motivation-solution.js`
3631

37-
Suppose you have a structure like:
32+
## API
3833

39-
```javascript
40-
class Button extends React.Component {
41-
render() {
42-
return (
43-
<button style={{background: this.props.color}}>
44-
{this.props.children}
45-
</button>
46-
);
47-
}
48-
}
34+
### `React.createContext`
4935

50-
class Message extends React.Component {
51-
render() {
52-
return (
53-
<div>
54-
{this.props.text} <Button color={this.props.color}>Delete</Button>
55-
</div>
56-
);
57-
}
58-
}
59-
60-
class MessageList extends React.Component {
61-
render() {
62-
const color = "purple";
63-
const children = this.props.messages.map((message) =>
64-
<Message text={message.text} color={color} />
65-
);
66-
return <div>{children}</div>;
67-
}
68-
}
69-
```
70-
71-
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:
72-
73-
```javascript{6,13-15,21,28-30,40-42}
74-
import PropTypes from 'prop-types';
75-
76-
class Button extends React.Component {
77-
render() {
78-
return (
79-
<button style={{background: this.context.color}}>
80-
{this.props.children}
81-
</button>
82-
);
83-
}
84-
}
85-
86-
Button.contextTypes = {
87-
color: PropTypes.string
88-
};
89-
90-
class Message extends React.Component {
91-
render() {
92-
return (
93-
<div>
94-
{this.props.text} <Button>Delete</Button>
95-
</div>
96-
);
97-
}
98-
}
99-
100-
class MessageList extends React.Component {
101-
getChildContext() {
102-
return {color: "purple"};
103-
}
104-
105-
render() {
106-
const children = this.props.messages.map((message) =>
107-
<Message text={message.text} />
108-
);
109-
return <div>{children}</div>;
110-
}
111-
}
112-
113-
MessageList.childContextTypes = {
114-
color: PropTypes.string
115-
};
36+
```js
37+
const {Provider, Consumer} = React.createContext(defaultValue);
11638
```
11739

118-
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`.
40+
Creates a `{ Provider, Consumer }` pair.
11941

120-
If `contextTypes` is not defined, then `context` will be an empty object.
42+
Optionally accepts a default value to be passed to Consumers without a Provider ancestor.
12143

122-
## Parent-Child Coupling
44+
### `Provider`
12345

124-
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):
46+
```js
47+
<Provider value={/* some value */}>
48+
```
12549

126-
```javascript
127-
import { BrowserRouter as Router, Route, Link } from 'react-router-dom';
50+
A React component that allows Consumers to subscribe to context changes.
12851

129-
const BasicExample = () => (
130-
<Router>
131-
<div>
132-
<ul>
133-
<li><Link to="/">Home</Link></li>
134-
<li><Link to="/about">About</Link></li>
135-
<li><Link to="/topics">Topics</Link></li>
136-
</ul>
52+
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.
13753

138-
<hr />
54+
### `Consumer`
13955

140-
<Route exact path="/" component={Home} />
141-
<Route path="/about" component={About} />
142-
<Route path="/topics" component={Topics} />
143-
</div>
144-
</Router>
145-
);
56+
```js
57+
<Consumer>
58+
{ value => { /* render something based on the context value */ } }
59+
</Consumer>
14660
```
14761

148-
By passing down some information from the `Router` component, each `Link` and `Route` can communicate back to the containing `Router`.
149-
150-
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.
62+
A React component that subscribes to context changes.
15163

152-
## Referencing Context in Lifecycle Methods
153-
154-
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:
155-
156-
- [`constructor(props, context)`](/docs/react-component.html#constructor)
157-
- [`componentWillReceiveProps(nextProps, nextContext)`](/docs/react-component.html#componentwillreceiveprops)
158-
- [`shouldComponentUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#shouldcomponentupdate)
159-
- [`componentWillUpdate(nextProps, nextState, nextContext)`](/docs/react-component.html#componentwillupdate)
64+
Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). This function receives the current context value and returns a React node. It will be called whenever the Provider's value is updated.
16065

16166
> Note:
162-
>
163-
> As of React 16, `componentDidUpdate` no longer receives `prevContext`.
164-
165-
## Referencing Context in Stateless Functional Components
166-
167-
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.
168-
169-
```javascript
170-
import PropTypes from 'prop-types';
67+
>
68+
> For more information about this pattern, see [render props](/docs/render-props.html).
17169
172-
const Button = ({children}, context) =>
173-
<button style={{background: context.color}}>
174-
{children}
175-
</button>;
70+
## Examples
17671

177-
Button.contextTypes = {color: PropTypes.string};
178-
```
179-
180-
## Updating Context
181-
182-
Don't do it.
72+
### Static Context
18373

184-
React has an API to update context, but it is fundamentally broken and you should not use it.
74+
Here is an example illustrating how you might inject a "theme" using context:
18575

186-
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.
76+
`embed:context/theme-example.js`
18777

188-
```javascript
189-
import PropTypes from 'prop-types';
78+
### Dynamic Context
19079

191-
class MediaQuery extends React.Component {
192-
constructor(props) {
193-
super(props);
194-
this.state = {type:'desktop'};
195-
}
80+
A more complex example with dynamic values for the theme:
19681

197-
getChildContext() {
198-
return {type: this.state.type};
199-
}
82+
**theme-context.js**
83+
`embed:context/theme-detailed-theme-context.js`
20084

201-
componentDidMount() {
202-
const checkMediaQuery = () => {
203-
const type = window.matchMedia("(min-width: 1025px)").matches ? 'desktop' : 'mobile';
204-
if (type !== this.state.type) {
205-
this.setState({type});
206-
}
207-
};
85+
**themed-button.js**
86+
`embed:context/theme-detailed-themed-button.js`
20887

209-
window.addEventListener('resize', checkMediaQuery);
210-
checkMediaQuery();
211-
}
88+
**app.js**
89+
`embed:context/theme-detailed-app.js`
21290

213-
render() {
214-
return this.props.children;
215-
}
216-
}
217-
218-
MediaQuery.childContextTypes = {
219-
type: PropTypes.string
220-
};
221-
```
91+
## Legacy API
22292

223-
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.
93+
> The legacy context API was deprecated in React 16.3 and will be removed in version 17.
94+
>
95+
> 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).

0 commit comments

Comments
 (0)