You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Creates a `{ Provider, Consumer }` pair. When React renders a context `Consumer`, it will read the current context value from the closest matching `Provider` above it in the tree.
118
+
Creates an Context object. When React renders a component that subscribes to this Context object it will read the current context value from the closest matching `Provider` above it in the tree.
121
119
122
-
The `defaultValue` argument is **only** used by a Consumer when it does not have a matching Provider above it in the tree. This can be helpful for testing components in isolation without wrapping them. Note: passing `undefined` as a Provider value does not cause Consumers to use `defaultValue`.
120
+
The `defaultValue` argument is **only** used when a component does not have a matching Provider above it in the tree. This can be helpful for testing components in isolation without wrapping them. Note: passing `undefined` as a Provider value does not cause consuming components to use `defaultValue`.
123
121
124
-
### `Provider`
122
+
### `Context.Provider`
125
123
126
124
```js
127
-
<Provider value={/* some value */}>
125
+
<MyContext.Provider value={/* some value */}>
128
126
```
129
127
130
-
A React component that allows Consumers to subscribe to context changes.
128
+
Every Context object comes with a Provider React component that allows consuming components to subscribe to context changes.
131
129
132
-
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.
130
+
Accepts a `value` prop to be passed to consuming components 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.
133
131
134
-
### `Consumer`
132
+
All consumers that are descendants of a Provider will re-render whenever the Provider's `value` prop changes. The propagation from Provider to its descendant consumers is not subject to the `shouldComponentUpdate` method, so the consumer is updated even when an ancestor component bails out of the update.
133
+
134
+
Changes are determined by comparing the new and old values using the same algorithm as [`Object.is`](//developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is#Description).
135
+
136
+
> Note
137
+
>
138
+
> The way changes are determined can cause some issues when passing objects as `value`: see [Caveats](#caveats).
139
+
140
+
### `Class.contextType`
135
141
136
142
```js
137
-
<Consumer>
138
-
{value=>/* render something based on the context value */}
139
-
</Consumer>
143
+
classMyClassextendsReact.Component {
144
+
componentDidMount() {
145
+
let value =this.context;
146
+
/* perform a side-effect at mount using the value of MyContext */
147
+
}
148
+
componentDidUpdate() {
149
+
let value =this.context;
150
+
/* ... */
151
+
}
152
+
componentWillUnmount() {
153
+
let value =this.context;
154
+
/* ... */
155
+
}
156
+
render() {
157
+
let value =this.context;
158
+
/* render something based on the value of MyContext */
159
+
}
160
+
}
161
+
MyClass.contextType= MyContext;
140
162
```
141
163
142
-
A React component that subscribes to context changes.
164
+
The `contextType` property on a class can be assigned a Context object created by [`React.createContext()`](#reactcreatecontext). This lets you consume the nearest current value of that Context type using `this.context`. You can reference this in any of the lifecycle methods including the render function.
143
165
144
-
Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). The function receives the current context value and returns a React node. The `value` argument passed to the function will be equal to the `value` prop of the closest Provider for this context above in the tree. If there is no Provider for this context above, the `value` argument will be equal to the `defaultValue` that was passed to `createContext()`.
166
+
> Note:
167
+
>
168
+
> You can only subscribe to a single context using this API. If you need to read more than one see [Consuming Multiple Contexts](#consuming-multiple-contexts).
169
+
>
170
+
> If you are using the experimental [public class fields syntax](https://babeljs.io/docs/plugins/transform-class-properties/), you can use a **static** class field to initialize your `contextType`.
145
171
146
-
> Note
147
-
>
148
-
> For more information about the 'function as a child' pattern, see [render props](/docs/render-props.html).
149
172
150
-
All Consumers that are descendants of a Provider will re-render whenever the Provider's `value` prop changes. The propagation from Provider to its descendant Consumers is not subject to the `shouldComponentUpdate` method, so the Consumer is updated even when an ancestor component bails out of the update.
173
+
```js
174
+
classMyClassextendsReact.Component {
175
+
static contextType = MyContext;
176
+
render() {
177
+
let value =this.context;
178
+
/* render something based on the value */
179
+
}
180
+
}
181
+
```
151
182
152
-
Changes are determined by comparing the new and old values using the same algorithm as [`Object.is`](//developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/is#Description).
183
+
### `Context.Consumer`
184
+
185
+
```js
186
+
<MyContext.Consumer>
187
+
{value=>/* render something based on the context value */}
188
+
</MyContext.Consumer>
189
+
```
190
+
191
+
A React component that subscribes to context changes. This lets you subscribe to a context within a [function component](/docs/components-and-props.html#function-and-class-components).
192
+
193
+
Requires a [function as a child](/docs/render-props.html#using-props-other-than-render). The function receives the current context value and returns a React node. The `value` argument passed to the function will be equal to the `value` prop of the closest Provider for this context above in the tree. If there is no Provider for this context above, the `value` argument will be equal to the `defaultValue` that was passed to `createContext()`.
153
194
154
195
> Note
155
196
>
156
-
> The way changes are determined can cause some issues when passing objects as `value`: see [Caveats](#caveats).
197
+
> For more information about the 'function as a child' pattern, see [render props](/docs/render-props.html).
157
198
158
199
## Examples
159
200
@@ -191,40 +232,6 @@ To keep context re-rendering fast, React needs to make each context consumer a s
191
232
192
233
If two or more context values are often used together, you might want to consider creating your own render prop component that provides both.
193
234
194
-
### Accessing Context in Lifecycle Methods
195
-
196
-
Accessing values from context in lifecycle methods is a relatively common use case. Instead of adding context to every lifecycle method, you just need to pass it as a prop, and then work with it just like you'd normally work with a prop.
197
-
198
-
`embed:context/lifecycles.js`
199
-
200
-
### Consuming Context with a HOC
201
-
202
-
Some types of contexts are consumed by many components (e.g. theme or localization). It can be tedious to explicitly wrap each dependency with a `<Context.Consumer>` element. A [higher-order component](/docs/higher-order-components.html) can help with this.
203
-
204
-
For example, a button component might consume a theme context like so:
205
-
206
-
`embed:context/higher-order-component-before.js`
207
-
208
-
That's alright for a few components, but what if we wanted to use the theme context in a lot of places?
209
-
210
-
We could create a higher-order component called `withTheme`:
211
-
212
-
`embed:context/higher-order-component.js`
213
-
214
-
Now any component that depends on the theme context can easily subscribe to it using the `withTheme` function we've created:
215
-
216
-
`embed:context/higher-order-component-usage.js`
217
-
218
-
### Forwarding Refs to Context Consumers
219
-
220
-
One issue with the render prop API is that refs don't automatically get passed to wrapped elements. To get around this, use `React.forwardRef`:
221
-
222
-
**fancy-button.js**
223
-
`embed:context/forwarding-refs-fancy-button.js`
224
-
225
-
**app.js**
226
-
`embed:context/forwarding-refs-app.js`
227
-
228
235
## Caveats
229
236
230
237
Because context uses reference identity to determine when to re-render, there are some gotchas that could trigger unintentional renders in consumers when a provider's parent re-renders. For example, the code below will re-render all consumers every time the Provider re-renders because a new object is always created for `value`:
0 commit comments