This site runs best with JavaScript enabled.

Migrating to React's New Context API

April 23, 2018

Let's compare the before/after of React's new context API.

With the recent release of React 16.3.0 came an official context API. You can learn more about the why and how behind this API from my previous blog post: "React's ⚛️ new Context API". Because of this significant change, I'm making an update to my advanced component patterns course on to use the new API rather than the old one. As I've been working on updating the course, I've been migrating from the old context API to the new one and I thought I'd show you some of those changes!

In my course, I have a section that shows how to write compound components (a trick I learned from Ryan Florence) that use the context API.

Example Usage

Here's the usage example of the Toggle component that exposes a compound components API:

1function Usage(props) {
2 return (
3 <Toggle onToggle={props.onToggle}>
4 <Toggle.On>The button is on</Toggle.On>
5 <Toggle.Off>The button is off</Toggle.Off>
6 <div>
7 <Toggle.Button />
8 </div>
9 </Toggle>
10 )

The idea behind the compound components pattern is that it allows you to have components that share implicit state with each other. You can actually use to accomplish it for the simple case, but in this case we need context to share any state at any place in the react tree.

The Old Context API

Here's the version of the implementation with the old context API:

1const TOGGLE_CONTEXT = '__toggle__'
2function ToggleOn({children}, context) {
3 const {on} = context[TOGGLE_CONTEXT]
4 return on ? children : null
6ToggleOn.contextTypes = {
7 [TOGGLE_CONTEXT]: PropTypes.object.isRequired,
9function ToggleOff({children}, context) {
10 const {on} = context[TOGGLE_CONTEXT]
11 return on ? null : children
13ToggleOff.contextTypes = {
14 [TOGGLE_CONTEXT]: PropTypes.object.isRequired,
16function ToggleButton(props, context) {
17 const {on, toggle} = context[TOGGLE_CONTEXT]
18 return <Switch on={on} onClick={toggle} {...props} />
20ToggleButton.contextTypes = {
21 [TOGGLE_CONTEXT]: PropTypes.object.isRequired,
23class Toggle extends React.Component {
24 static On = ToggleOn
25 static Off = ToggleOff
26 static Button = ToggleButton
27 static defaultProps = {onToggle: () => {}}
28 static childContextTypes = {
29 [TOGGLE_CONTEXT]: PropTypes.object.isRequired,
30 }
31 state = {on: false}
32 toggle = () =>
33 this.setState(
34 ({on}) => ({on: !on}),
35 () => this.props.onToggle(this.state.on),
36 )
37 getChildContext() {
38 return {
40 on: this.state.on,
41 toggle: this.toggle,
42 },
43 }
44 }
45 render() {
46 return <div>{this.props.children}</div>
47 }

With the old API, you had to specify a string for what context your component would provide in getChildContext and childContextTypes and then specify that same string in the consuming components with contextTypes. I never liked this indirection and normally avoided the problem by making a variable like I do above. In addition, having to attach static properties to the consumers so they could accept the context values wasn't my favorite thing to do either.

Another problem with this API is that it didn't allow values to be updated through a shouldComponentUpdate that returned false. So I had an entire other lesson to demonstrate how to work around that issue: "Rerender Descendants Through shouldComponentUpdate" (hat-tip to Michael Jackson and Ryan Florence for react-broadcast).

The New Context API

The new API doesn't have these problems, which is some of the reason I'm so excited about it. Here's my new version of this same exercise:

1const ToggleContext = React.createContext({
2 on: false,
3 toggle: () => {},
6class Toggle extends React.Component {
7 static On = ({children}) => (
8 <ToggleContext.Consumer>
9 {({on}) => (on ? children : null)}
10 </ToggleContext.Consumer>
11 )
12 static Off = ({children}) => (
13 <ToggleContext.Consumer>
14 {({on}) => (on ? null : children)}
15 </ToggleContext.Consumer>
16 )
17 static Button = props => (
18 <ToggleContext.Consumer>
19 {({on, toggle}) => <Switch on={on} onClick={toggle} {...props} />}
20 </ToggleContext.Consumer>
21 )
22 toggle = () =>
23 this.setState(
24 ({on}) => ({on: !on}),
25 () => this.props.onToggle(this.state.on),
26 )
27 state = {on: false, toggle: this.toggle}
28 render() {
29 return (
30 <ToggleContext.Provider value={this.state}>
31 {this.props.children}
32 </ToggleContext.Provider>
33 )
34 }

A few things stand out to me in the changes here. As I said, the problems with the old API are gone. Now, rather than the indirection of strings you have explicit components that you must use in order to provide and consume context. You no longer need odd properties to make things work but instead use simple components.

Things are still a tad verbose with those compound components though. Every one of them needs to use the consumer (just like every one of them needed static properties). You can solve that problem (for both APIs) with a render-prop-based Higher Order Component. In this case I wouldn't bother though, it's pretty simple.

The other problem that goes away is updates through shouldComponentUpdate returning false. React's new context API takes care of that for you.

Another thing I love about this is because the consumers are using a render prop API they are highly composable making it possible to do just about anything with them and expose a nice clean API on top because of the dynamic composability of render props (as opposed to the static composability of the old API).

Issues with the New API

One very common pitfall that I'm sure we'll be battling with forever is the importance that the value prop you give to the Provider component is only changed when you want consumers to re-render. This means that doing value={{on: this.state.on, toggle: this.toggle}} in our render method is inadvisable because that creates a new object every time render is called, even if state didn't actually change. Because it's a new object, all the consumers will also be re-rendered.

The impact of this will vary greatly in practice, but in general it's better to provide a value that only changes when state changes (and consumers need to be re-rendered). This is why I say value={this.state}. If you'd prefer not to expose the entire state object to consumers, then you could use this trick I got from Ryan Florence.

One slight issue I have with this is that I have to put the toggle method into state and that feels odd to me, but it's an implementation detail that's not a big deal I think.


After converting a few context using components over to the new API I'm reassured that the React team gave us something brilliant. I love this new API and I'm eager to see how the community embraces it! I hope you enjoy it. Good luck!

P.S. I should note that if you're unable to upgrade to react@16.3.0, you can still use this API via a polyfill: create-react-context.

Learn more about React from me:

  • Frontend Masters — My Advanced Component Patterns workshop I gave in person in Minneapolis in April! It should be made a course soon, but it's available for review by subscribers today!
  • — I'm giving my Advanced Component Patterns workshop in person in Portland in July!
  • — I'm giving my ES6 and Beyond workshop in person in Salt Lake City in July!
  • — I'm giving my Intro to React workshop in person in Salt Lake City in August!
  • — I'm giving my Advanced Component Patterns workshop in person in Salt Lake City in August!

Things to not miss:

Discuss on TwitterEdit post on GitHub

Share article
loading relevant upcoming workshops...
Kent C. Dodds

Kent C. Dodds is a JavaScript software engineer and teacher. He's taught hundreds of thousands of people how to make the world a better place with quality software development tools and practices. He lives with his wife and four kids in Utah.