---
id: context
title: Context
permalink: docs/context.html
---
Context provides a way to pass data through the component tree without having to pass props down manually at every level.
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.
- [When to Use Context ](#when-to-use-context )
- [API ](#api )
- [React.createContext ](#reactcreatecontext )
- [Provider ](#provider )
- [Consumer ](#consumer )
- [Examples ](#examples )
- [Static Context ](#static-context )
- [Dynamic Context ](#dynamic-context )
- [Consuming Multiple Contexts ](#consuming-multiple-contexts )
- [Accessing Context in Lifecycle Methods ](#accessing-context-in-lifecycle-methods )
- [Forwarding Refs to Context Consumers ](#forwarding-refs-to-context-consumers )
- [Legacy API ](#legacy-api )
## When to Use Context
Context is designed to share data that can be considered "global" for a tree of React components, such as the current authenticated user, theme, or preferred language. For example, in the code below we manually thread through a "theme" prop in order to style the Button component:
`embed:context/motivation-problem.js`
Using context, we can avoid passing props through intermediate elements:
`embed:context/motivation-solution.js`
> Note
>
> Don't use context just to avoid passing props a few levels down. Stick to cases where the same data needs to accessed in many components at multiple levels.
## API
### `React.createContext`
```js
const {Provider, Consumer} = React.createContext(defaultValue);
```
Creates a `{ Provider, Consumer }` pair.
Optionally accepts a default value to be passed to Consumers without a Provider ancestor.
### `Provider`
```js
< Provider value = {/* some value * / } >
```
All doc updates forv15.5 (#9359)
* `react-addons-test-utils` -> `react-dom/test-utils`
Updating all references and docs on the `React.addons.TestUtils` and the
shallow renderer to refer to the correct targets.
Instead of:
```
const React = require('react');
// ...
React.addons.Testutils
// or
const ReactTestUtils = require('react-addons-test-utils');
```
we now show:
```
const ReactTestUtils = require('react-dom/test-utils');
```
And for shallow renderer, instead of:
```
const shallowRenderer = TestUtils.createRenderer();
```
we now show:
```
const shallowRenderer = require('react-test-renderer/shallow');
```
* Update the 'prev' and 'next' attributes of 'add-ons' docs
These flags are used to set arrow links to easily navigate through the
documents. They were wrong or missing in some of the 'add-ons' pages and
this bothered me when manually testing the updates from the previous
commit.
* Update syntax for instantiating shallow renderer
Missed this when updating the docs for the changes to shallow-renderer
in React 15.5.
* Fix pointers in addons docs
Thanks @bvaughn for catching this
* Make example of shallow renderer more consistent
We should show using the same variable names between code samples.
* Make names in example even more consistent
We should use the same variable name for the same thing across examples.
`renderer` -> `shallowRenderer`.
* Update docs to deprecate React<CSS>TransitionGroup
- removes link to the docs about `ReactCSSTransitionGroup` and
`ReactTransitionGroup` from the main navigation
- updates 'prev' and 'next' pointers to skip this page
- adds deprecation warning to the top of the page
- remove references to these modules from the packages README
- updates 'add-ons' main page to list this as a deprecated add-on
* Update `React.createClass` to `createReactClass` in the docs
The `React.createClass` method is being deprecated in favor of
`createReactClass`.
* Remove 'React.createClass' from top level API docs
It no longer makes sense to have a section for the 'createClass' method
in this page, since it won't be available as a top level method on
'React'.
I initially was going to pull the section about 'createClass' into a
separate page to add under 'addons' but it was short and duplicative of
the 'react-without-es6' docs. So I just linked to those.
* Remove *most* `React.PropTypes` from the docs
I am doing the docs for `context` in a separate commit because that case
was a bit less clear-cut.
We will no longer support `React.PropTypes` as a built-in feature of
React, and instead should direct folks to use the `PropTypes` project
that stands alone.
Rather than retaining the `React.PropTypes` examples and just revamping
them to show the use of the stand-alone `PropTypes` library with React,
it makes more sense to direct people to that project and reduce the
perceived API area and complexity of React core. The proper place to
document `PropTypes` is in the README or docs of that project, not in
React docs.
* Update `context` docs to not use `React.PropTypes`
We use `React.PropTypes` to define the `contextType` for the `context`
feature of React. It's unclear how this will work once `React.PropTypes`
is replaced by the external `PropTypes` library. Some options;
a) Deprecate `context`, either in v16 or shortly after. Seems reasonable
based on the intense warnings against using context that we have in the
docs -
https://facebook.github.io/react/docs/context.html#why-not-to-use-context
**Except** that probably some widely used libraries depend on it, like
`React-Router`.
b) Expect users will use external `PropTypes` library when defining
`contextTypes` and just don't do our `checkReactTypeSpec` against them
any more in v16.
c) Stop masking context and pass the whole context
unmasked everywhere. Worst option, do not recommend.
I went with `b` and assume that, for now, we will get users to use the
external `PropTypes` when defining context. I will update this PR if we
want a different approach.
* Remove 'addons' items from left nav, and deprecate 'addons' doc page
The plan:
[X] Remove links to 'addons' items from main navigation
[X] Add deprecation notices where appropriate, and update syntax to show
using the separate modules.
[ ] Update other references to 'React.addons' in docs. Coming in next
commit.
--- blocked but coming in future PRs
[ ] Link to a blog post describing the new locations of add-ons in the
deprecation notice on the '/docs/addons.html' page. Blocked until we
actually publish that blog post.
[ ] Move the docs for each add-on to the actual github repo where it now
lives.
[ ] Redirect the old add-ons doc permalinks to the docs in the separate
github repos for those modules.
[ ] Remove the old add-ons doc markdown files from React core docs.
* Remove references to `React.addons` from docs
Just misc. places where we referenced the 'addons' feature. All gone!
8 years ago
A React component that allows Consumers to subscribe to context changes.
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 >
```
A React component that subscribes to context changes.
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. All consumers are re-rendered whenever the Provider value changes. 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 ).
> Note
>
> For more information about this pattern, see [render props](/docs/render-props.html).
## Examples
### Dynamic Context
A more complex example with dynamic values for the theme:
**theme-context.js**
`embed:context/theme-detailed-theme-context.js`
**themed-button.js**
`embed:context/theme-detailed-themed-button.js`
**app.js**
`embed:context/theme-detailed-app.js`
## Consuming Multiple Contexts
To keep context re-rendering fast, React needs to make each context consumer a separate node in the tree.
`embed:context/multiple-contexts.js`
If two or more context values are often used together, you might want to consider creating your own render prop component that provides both.
## Accessing Context in Lifecycle Methods
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.
`embed:context/lifecycles.js`
## Forwarding Refs to Context Consumers
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` :
**fancy-button.js**
`embed:context/forwarding-refs-fancy-button.js`
**app.js**
`embed:context/forwarding-refs-app.js`
## Legacy API
> Note
>
> 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. The legacy API will be removed in a future major React version. Read the [legacy context docs here](/docs/legacy-context.html).
