In addition, the following three languages have completed translating most of the React Docs! 🎉

• Spanish: es.reactjs.org
• Japanese: ja.reactjs.org
• Brazilian Portuguese: pt-br.reactjs.org

Special congratulations to Alejandro Ñáñez Ortiz, Rainer Martínez Fraga, David Morales, Miguel Alejandro Bolivar Portilla, and all the contributors to the Spanish translation for being the first to completely translate the core pages of the docs!

Why Localization Matters

React already has many meetups and conferences around the world, but many programmers don’t use English as their primary language. We’d love to support local communities who use React by making our documentation available in most popular languages.

In the past, React community members have created unofficial translations for Chinese, Arabic, and Korean; by making an official channel for these translated docs we’re hoping to make them easier to find and help make sure that non-English-speaking users of React aren’t left behind.

Contributing

If you would like to help out on a current translation, check out the Languages page and click on the “Contribute” link for your language.

Can’t find your language? If you’d like to maintain your language’s translation fork, follow the instructions in the translation repo!

Backstory

Hi everyone! I’m Nat! You may know me as the polyhedra lady. For the past few weeks, I’ve been helping the React team coordinate their translation effort. Here’s how I did it.

Our original approach for translations was to use a SaaS platform that allows users to submit translations. There was already a pull request to integrate it and my original responsibility was to finish that integration. However, we had concerns about the feasibility of that integration and the current quality of translations on the platform. Our primary concern was ensuring that translations kept up to date with the main repo and didn’t become “stale”.

Dan encouraged me to look for alternate solutions, and we stumbled across how Vue maintained its translations — through different forks of the main repo on GitHub. In particular, the Japanese translation used a bot to periodically check for changes in the English repo and submits pull requests whenever there is a change.

This approach appealed to us for several reasons:

• It was less code integration to get off the ground.
• It encouraged active maintainers for each repo to ensure quality.
• Contributors already understand GitHub as a platform and are motivated to contribute directly to the React organization.

We started off with an initial trial period of three languages: Spanish, Japanese, and Simplified Chinese. This allowed us to work out any kinks in our process and make sure future translations are set up for success. I wanted to give the translation teams freedom to choose whatever tools they felt comfortable with. The only requirement is a checklist that outlines the order of importance for translating pages.

After the trial period, we were ready to accept more languages. I created a script to automate the creation of the new language repo, and a site, Is React Translated Yet?, to track progress on the different translations. We started 10 new translations on our first day alone!

Because of the automation, the rest of the maintenance went mostly smoothly. We eventually created a Slack channel to make it easier for translators to share information, and I released a guide solidifying the responsibilities of maintainers. Allowing translators to talk with each other was a great boon — for example, the Arabic, Persian, and Hebrew translations were able to talk to each other in order to get right-to-left text working!

The Bot

The most challenging part was getting the bot to sync changes from the English version of the site. Initially we were using the che-tsumi bot created by the Japanese Vue translation team, but we soon decided to build our own bot to suit our needs. In particular, the che-tsumi bot works by cherry picking new commits. This ended up causing a cavalade of new issues that were interconnected, especially when Hooks were released.

In the end, we decided that instead of cherry picking each commit, it made more sense to merge all new commits and create a pull request around once a day. Conflicts are merged as-is and listed in the pull request, leaving a checklist for maintainers to fix.

Creating the sync script was easy enough: it downloads the translated repo, adds the original as a remote, pulls from it, merges the conflicts, and creates a pull request.

The problem was finding a place for the bot to run. I’m a frontend developer for a reason — Heroku and its ilk are alien to me and endlessly frustrating. In fact, until this past Tuesday, I was running the script by hand on my local machine!

The biggest challenge was space. Each fork of the repo is around 100MB — which takes minutes to clone on my local machine. We have 32 forks, and the free tiers or most deployment platforms I checked limited you to 512MB of storage.

After lots of notepad calculations, I found a solution: delete each repo once we’ve finished the script and limit the concurrency of sync scripts that run at once to be within the storage requirements. Luckily, Heroku dynos have a much faster Internet connection and are able to clone even the React repo quickly.

There were other smaller issues that I ran into. I tried using the Heroku Scheduler add-on so I didn’t have to write any actual watch code, but it end up running too inconsistently, and I had an existential meltdown on Twitter when I couldn’t figure out how to send commits from the Heroku dyno. But in the end, this frontend engineer was able to get the bot working!

There are, as always, improvements I want to make to the bot. Right now it doesn’t check whether there is an outstanding pull request before pushing another one. It’s still hard to tell the exact change that happened in the original source, and it’s possible to miss out on a needed translation change. But I trust the maintainers we’ve chosen to work through these issues, and the bot is open source if anyone wants to help me make these improvements!

Thanks

Finally, I would like to extend my gratitude to the following people and groups:

• All the translation maintainers and contributors who are helping translate React to more than thirty languages.
• The Vue.js Japan User Group for initiating the idea of having bot-managed translations, and especially Hanatani Takuma for helping us understand their approach and helping maintain the Japanese translation.
• Soichiro Miki for many contributions and thoughtful comments on the overall translation process, as well as for maintaining the Japanese translation.
• Eric Nakagawa for managing our previous translation process.
• Brian Vaughn for setting up the languages page and managing all the subdomains.

And finally, thank you to Dan Abramov for giving me this opportunity and being a great mentor along the way.

What Are Hooks?

Hooks let you use state and other React features without writing a class. You can also build your own Hooks to share reusable stateful logic between components.

If you’ve never heard of Hooks before, you might find these resources interesting:

• Introducing Hooks explains why we’re adding Hooks to React.
• Hooks at a Glance is a fast-paced overview of the built-in Hooks.
• Building Your Own Hooks demonstrates code reuse with custom Hooks.
• Making Sense of React Hooks explores the new possibilities unlocked by Hooks.
• useHooks.com showcases community-maintained Hooks recipes and demos.

You don’t have to learn Hooks right now. Hooks have no breaking changes, and we have no plans to remove classes from React. The Hooks FAQ describes the gradual adoption strategy.

No Big Rewrites

We don’t recommend rewriting your existing applications to use Hooks overnight. Instead, try using Hooks in some of the new components, and let us know what you think. Code using Hooks will work side by side with existing code using classes.

Can I Use Hooks Today?

Yes! Starting with 16.8.0, React includes a stable implementation of React Hooks for:

• React DOM
• React DOM Server
• React Test Renderer
• React Shallow Renderer

Note that to enable Hooks, all React packages need to be 16.8.0 or higher. Hooks won’t work if you forget to update, for example, React DOM.

React Native will support Hooks in the 0.59 release.

Tooling Support

React Hooks are now supported by React DevTools. They are also supported in the latest Flow and TypeScript definitions for React. We strongly recommend enabling a new lint rule called eslint-plugin-react-hooks to enforce best practices with Hooks. It will soon be included into Create React App by default.

What’s Next

We described our plan for the next months in the recently published React Roadmap.

Note that React Hooks don’t cover all use cases for classes yet but they’re very close. Currently, only getSnapshotBeforeUpdate() and componentDidCatch() methods don’t have equivalent Hooks APIs, and these lifecycles are relatively uncommon. If you want, you should be able to use Hooks in most of the new code you’re writing.

Even while Hooks were in alpha, the React community created many interesting examples and recipes using Hooks for animations, forms, subscriptions, integrating with other libraries, and so on. We’re excited about Hooks because they make code reuse easier, helping you write your components in a simpler way and make great user experiences. We can’t wait to see what you’ll create next!

Testing Hooks

We have added a new API called ReactTestUtils.act() in this release. It ensures that the behavior in your tests matches what happens in the browser more closely. We recommend to wrap any code rendering and triggering updates to your components into act() calls. Testing libraries can also wrap their APIs with it (for example, react-testing-library’s render and fireEvent utilities do this).

For example, the counter example from this page can be tested like this:

import React from 'react';
import ReactDOM from 'react-dom';
import { act } from 'react-dom/test-utils';
import Counter from './Counter';

let container;

beforeEach(() => {
  container = document.createElement('div');
  document.body.appendChild(container);
});

afterEach(() => {
  document.body.removeChild(container);
  container = null;
});

it('can render and update a counter', () => {
  // Test first render and effect
  act(() => {
    ReactDOM.render(<Counter />, container);
  });
  const button = container.querySelector('button');
  const label = container.querySelector('p');
  expect(label.textContent).toBe('You clicked 0 times');
  expect(document.title).toBe('You clicked 0 times');

  // Test second render and effect
  act(() => {
    button.dispatchEvent(new MouseEvent('click', {bubbles: true}));
  });
  expect(label.textContent).toBe('You clicked 1 times');
  expect(document.title).toBe('You clicked 1 times');
});

The calls to act() will also flush the effects inside of them.

If you need to test a custom Hook, you can do so by creating a component in your test, and using your Hook from it. Then you can test the component you wrote.

To reduce the boilerplate, we recommend using react-testing-library which is designed to encourage writing tests that use your components as the end users do.

Thanks

We’d like to thank everybody who commented on the Hooks RFC for sharing their feedback. We’ve read all of your comments and made some adjustments to the final API based on them.

Installation

React

React v16.8.0 is available on the npm registry.

To install React 16 with Yarn, run:

yarn add react@^16.8.0 react-dom@^16.8.0

To install React 16 with npm, run:

npm install --save react@^16.8.0 react-dom@^16.8.0

We also provide UMD builds of React via a CDN:

<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>

Refer to the documentation for detailed installation instructions.

ESLint Plugin for React Hooks

Note

As mentioned above, we strongly recommend using the eslint-plugin-react-hooks lint rule.

If you’re using Create React App, instead of manually configuring ESLint you can wait for the next version of react-scripts which will come out shortly and will include this rule.

Assuming you already have ESLint installed, run:

# npm
npm install eslint-plugin-react-hooks --save-dev

# yarn
yarn add eslint-plugin-react-hooks --dev

Then add it to your ESLint configuration:

{
  "plugins": [
    // ...
    "react-hooks"
  ],
  "rules": {
    // ...
    "react-hooks/rules-of-hooks": "error"
  }
}

Changelog

React

• Add Hooks — a way to use state and other React features without writing a class. (@acdlite et al. in #13968)
• Improve the useReducer Hook lazy initialization API. (@acdlite in #14723)

React DOM

• Bail out of rendering on identical values for useState and useReducer Hooks. (@acdlite in #14569)
• Don’t compare the first argument passed to useEffect/useMemo/useCallback Hooks. (@acdlite in #14594)
• Use Object.is algorithm for comparing useState and useReducer values. (@Jessidhia in #14752)
• Support synchronous thenables passed to React.lazy(). (@gaearon in #14626)
• Render components with Hooks twice in Strict Mode (DEV-only) to match class behavior. (@gaearon in #14654)
• Warn about mismatching Hook order in development. (@threepointone in #14585 and @acdlite in #14591)
• Effect clean-up functions must return either undefined or a function. All other values, including null, are not allowed. @acdlite in #14119

React Test Renderer

• Support Hooks in the shallow renderer. (@trueadm in #14567)
• Fix wrong state in shouldComponentUpdate in the presence of getDerivedStateFromProps for Shallow Renderer. (@chenesan in #14613)
• Add ReactTestRenderer.act() and ReactTestUtils.act() for batching updates so that tests more closely match real behavior. (@threepointone in #14744)

ESLint Plugin: React Hooks

• Initial release. (@calebmer in #13968)
• Fix reporting after encountering a loop. (@calebmer and @Yurickh in #14661)
• Don’t consider throwing to be a rule violation. (@sophiebits in #14040)

Hooks Changelog Since Alpha Versions

The above changelog contains all notable changes since our last stable release (16.7.0). As with all our minor releases, none of the changes break backwards compatibility.

If you’re currently using Hooks from an alpha build of React, note that this release does contain some small breaking changes to Hooks. We don’t recommend depending on alphas in production code. We publish them so we can make changes in response to community feedback before the API is stable.

Here are all breaking changes to Hooks that have been made since the first alpha release:

• Remove useMutationEffect. (@sophiebits in #14336)
• Rename useImperativeMethods to useImperativeHandle. (@threepointone in #14565)
• Bail out of rendering on identical values for useState and useReducer Hooks. (@acdlite in #14569)
• Don’t compare the first argument passed to useEffect/useMemo/useCallback Hooks. (@acdlite in #14594)
• Use Object.is algorithm for comparing useState and useReducer values. (@Jessidhia in #14752)
• Render components with Hooks twice in Strict Mode (DEV-only). (@gaearon in #14654)
• Improve the useReducer Hook lazy initialization API. (@acdlite in #14723)

Why Is This Bugfix a Minor Instead of a Patch?

React follows semantic versioning. Typically, this means that we use patch versions for bugfixes, and minors for new (non-breaking) features. However, we reserve the option to release minor versions even if they do not include new features. The motivation is to reserve patches for changes that have a very low chance of breaking. Patches are the most important type of release because they sometimes contain critical bugfixes. That means patch releases have a higher bar for reliability. It’s unacceptable for a patch to introduce additional bugs, because if people come to distrust patches, it compromises our ability to fix critical bugs when they arise — for example, to fix a security vulnerability.

We never intend to ship bugs. React has a hard-earned reputation for stability, and we intend to keep it that way. We thoroughly test every version of React before releasing. This includes unit tests, generative (fuzzy) tests, integration tests, and internal dogfooding across tens of thousands of components. However, sometimes we make mistakes. That’s why, going forward, our policy will be that if a release contains non-trivial changes, we will bump the minor version, even if the external behavior is the same. We’ll also bump the minor when changing unstable_-prefixed APIs.

Can I Use Hooks Yet?

Not yet, but soon!

At React Conf, we said that 16.7 would be the first release to include Hooks. This was a mistake. We shouldn’t have attached a specific version number to an unreleased feature. We’ll avoid this in the future.

Although 16.7 does not include Hooks, please do not infer anything about the timeline of the Hooks launch. Our plans for Hooks are unchanged:

• The Hooks proposal was accepted (with minor planned changes in response to feedback).
• The implementation was merged into the React repo (behind a feature flag).
• We’re currently in the testing phase, and you can expect a public release within a few months.

We’ve heard from many people who want to start using Hooks in their apps. We also can’t wait to ship them! But because Hooks changes how we write React components, we are taking extra time to get the details right. We appreciate your patience as we prepare this exciting new feature for widespread, ahem, use.

Learn more about our roadmap in our previous post.

Installation

React v16.7.0 is available on the npm registry.

To install React 16 with Yarn, run:

yarn add react@^16.7.0 react-dom@^16.7.0

To install React 16 with npm, run:

npm install --save react@^16.7.0 react-dom@^16.7.0

We also provide UMD builds of React via a CDN:

<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>

Refer to the documentation for detailed installation instructions.

Changelog

React DOM

• Fix performance of React.lazy for large numbers of lazily-loaded components. (@acdlite in #14429)
• Clear fields on unmount to avoid memory leaks. (@trueadm in #14276)
• Fix bug with SSR and context when mixing react-dom/server@16.6 and react@<16.6. (@gaearon in #14291)
• Fix a performance regression in profiling mode. (@bvaughn in #14383)

Scheduler (Experimental)

• Post to MessageChannel instead of window. (@acdlite in #14234)
• Reduce serialization overhead. (@developit in #14249)
• Fix fallback to setTimeout in testing environments. (@bvaughn in #14358)
• Add methods for debugging. (@mrkev in #14053)

tl;dr

We plan to split the rollout of new React features into the following milestones:

• React 16.6 with Suspense for Code Splitting (already shipped)
• A minor 16.x release with React Hooks (~Q1 2019)
• A minor 16.x release with Concurrent Mode (~Q2 2019)
• A minor 16.x release with Suspense for Data Fetching (~mid 2019)

(The original version of this post used exact version numbers. We edited it to reflect that there might need to be a few other minor releases in the middle between these ones.)

These are estimates, and the details may change as we’re further along. There’s at least two more projects we plan to complete in 2019. They require more exploration and aren’t tied to a particular release yet:

• Modernizing React DOM
• Suspense for Server Rendering

We expect to get more clarity on their timeline in the coming months.

Note

This post is just a roadmap — there is nothing in it that requires your immediate attention. When each of these features are released, we’ll publish a full blog post announcing them.

Release Timeline

We have a single vision for how all of these features fit together, but we’re releasing each part as soon as it is ready so that you can test and start using them sooner. The API design doesn’t always make sense when looking at one piece in isolation; this post lays out the major parts of our plan to help you see the whole picture. (See our versioning policy to learn more about our commitment to stability.)

The gradual release strategy helps us refine the APIs, but the transitional period when some things aren’t ready can be confusing. Let’s look at what these different features mean for your app, how they relate to each other, and when you can expect to start learning and using them.

React 16.6 (shipped): The One with Suspense for Code Splitting

Suspense refers to React’s new ability to “suspend” rendering while components are waiting for something, and display a loading indicator. In React 16.6, Suspense supports only one use case: lazy loading components with React.lazy() and <React.Suspense>.

// This component is loaded dynamically
const OtherComponent = React.lazy(() => import('./OtherComponent'));

function MyComponent() {
  return (
    <React.Suspense fallback={<Spinner />}>
      <div>
        <OtherComponent />
      </div>
    </React.Suspense>
  );
}

Code splitting with React.lazy() with <React.Suspense> is documented in the Code Splitting guide. You can find another practical explanation in this article.

We have been using Suspense for code splitting at Facebook since July, and expect it to be stable. There’s been a few regressions in the initial public release in 16.6.0, but they were fixed in 16.6.3.

Code splitting is just the first step for Suspense. Our longer term vision for Suspense involves letting it handle data fetching too (and integrate with libraries like Apollo). In addition to a convenient programming model, Suspense also provides better user experience in Concurrent Mode. You’ll find information about these topics further below.

Status in React DOM: Available since React 16.6.0.

Status in React DOM Server: Suspense is not available in the server renderer yet. This isn’t for the lack of attention. We’ve started work on a new asynchronous server renderer that will support Suspense, but it’s a large project and will take a good chunk of 2019 to complete.

Status in React Native: Bundle splitting isn’t very useful in React Native, but there’s nothing technically preventing React.lazy() and <Suspense> from working when given a Promise to a module.

Recommendation: If you only do client rendering, we recommend widely adopting React.lazy() and <React.Suspense> for code splitting React components. If you do server rendering, you’ll have to wait with adoption until the new server renderer is ready.

React 16.x (~Q1 2019): The One with Hooks

Hooks let you use features like state and lifecycle from function components. They also let you reuse stateful logic between components without introducing extra nesting in your tree.

function Example() {
  // Declare a new state variable, which we'll call "count"
  const [count, setCount] = useState(0);

  return (
   <div>
     <p>You clicked {count} times</p>
     <button onClick={() => setCount(count + 1)}>
       Click me
     </button>
   </div>
 );
}

Hooks introduction and overview are good places to start. Watch these talks for a video introduction and a deep dive. The FAQ should answer most of your further questions. To learn more about the motivation behind Hooks, you can read this article. Some of the rationale for the API design of Hooks is explained in this RFC thread reply.

We have been dogfooding Hooks at Facebook since September. We don’t expect major bugs in the implementation. Hooks are only available in the 16.7 alpha versions of React. Some of their API is expected to change in the final version (see the end of this comment for details). It is possible that the minor release with Hooks might not be React 16.7.

Hooks represent our vision for the future of React. They solve both problems that React users experience directly (“wrapper hell” of render props and higher-order components, duplication of logic in lifecycle methods), and the issues we’ve encountered optimizing React at scale (such as difficulties in inlining components with a compiler). Hooks don’t deprecate classes. However, if Hooks are successful, it is possible that in a future major release class support might move to a separate package, reducing the default bundle size of React.

Status in React DOM: The first version of react and react-dom supporting Hooks is 16.7.0-alpha.0. We expect to publish more alphas over the next months (at the time of writing, the latest one is 16.7.0-alpha.2). You can try them by installing react@next with react-dom@next. Don’t forget to update react-dom — otherwise Hooks won’t work.

Status in React DOM Server: The same 16.7 alpha versions of react-dom fully support Hooks with react-dom/server.

Status in React Native: There is no officially supported way to try Hooks in React Native yet. If you’re feeling adventurous, check out this thread for unofficial instructions. There is a known issue with useEffect firing too late which still needs to be solved.

Recommendation: When you’re ready, we encourage you to start trying Hooks in new components you write. Make sure everyone on your team is on board with using them and familiar with this documentation. We don’t recommend rewriting your existing classes to Hooks unless you planned to rewrite them anyway (e.g. to fix bugs). Read more about the adoption strategy here.

React 16.x (~Q2 2019): The One with Concurrent Mode

Concurrent Mode lets React apps be more responsive by rendering component trees without blocking the main thread. It is opt-in and allows React to interrupt a long-running render (for example, rendering a new feed story) to handle a high-priority event (for example, text input or hover). Concurrent Mode also improves the user experience of Suspense by skipping unnecessary loading states on fast connections.

Note

You might have previously heard Concurrent Mode being referred to as “async mode”. We’ve changed the name to Concurrent Mode to highlight React’s ability to perform work on different priority levels. This sets it apart from other approaches to async rendering.

// Two ways to opt in:

// 1. Part of an app (not final API)
<React.unstable_ConcurrentMode>
  <Something />
</React.unstable_ConcurrentMode>

// 2. Whole app (not final API)
ReactDOM.unstable_createRoot(domNode).render(<App />);

There is no documentation written for the Concurrent Mode yet. It is important to highlight that the conceptual model will likely be unfamiliar at first. Documenting its benefits, how to use it efficiently, and its pitfalls is a high priority for us, and will be a prerequisite for calling it stable. Until then, Andrew’s talk is the best introduction available.

Concurrent Mode is much less polished than Hooks. Some APIs aren’t properly “wired up” yet and don’t do what they’re expected to. At the time of writing this post, we don’t recommend using it for anything except very early experimentation. We don’t expect many bugs in Concurrent Mode itself, but note that components that produce warnings in <React.StrictMode> may not work correctly. On a separate note, we’ve seen that Concurrent Mode surfaces performance problems in other code which can sometimes be mistaken for performance issues in Concurrent Mode itself. For example, a stray setInterval(fn, 1) call that runs every millisecond would have a worse effect in Concurrent Mode. We plan to publish more guidance about diagnosing and fixing issues like this as part of this release’s documentation.

Concurrent Mode is a big part of our vision for React. For CPU-bound work, it allows non-blocking rendering and keeps your app responsive while rendering complex component trees. That’s demoed in the first part of our JSConf Iceland talk. Concurrent Mode also makes Suspense better. It lets you avoid flickering a loading indicator if the network is fast enough. It’s hard to explain without seeing so Andrew’s talk is the best resource available today. Concurrent Mode relies on a cooperative main thread scheduler, and we are collaborating with the Chrome team to eventually move this functionality into the browser itself.

Status in React DOM: A very unstable version of Concurrent Mode is available behind an unstable_ prefix in React 16.6 but we don’t recommend trying it unless you’re willing to often run into walls or missing features. The 16.7 alphas include React.ConcurrentMode and ReactDOM.createRoot without an unstable_ prefix, but we’ll likely keep the prefix in 16.7, and only document and mark Concurrent Mode as stable in this future minor release.

Status in React DOM Server: Concurrent Mode doesn’t directly affect server rendering. It will work with the existing server renderer.

Status in React Native: The current plan is to delay enabling Concurrent Mode in React Native until React Fabric project is near completion.

Recommendation: If you wish to adopt Concurrent Mode in the future, wrapping some component subtrees in <React.StrictMode> and fixing the resulting warnings is a good first step. In general it’s not expected that legacy code would immediately be compatible. For example, at Facebook we mostly intend to use the Concurrent Mode in the more recently developed codebases, and keep the legacy ones running in the synchronous mode for the near future.

React 16.x (~mid 2019): The One with Suspense for Data Fetching

As mentioned earlier, Suspense refers to React’s ability to “suspend” rendering while components are waiting for something, and display a loading indicator. In the already shipped React 16.6, the only supported use case for Suspense is code splitting. In this future minor release, we’d like to provide officially supported ways to use it for data fetching too. We’ll provide a reference implementation of a basic “React Cache” that’s compatible with Suspense, but you can also write your own. Data fetching libraries like Apollo and Relay will be able to integrate with Suspense by following a simple specification that we’ll document.

// React Cache for simple data fetching (not final API)
import {unstable_createResource} from 'react-cache';

// Tell React Cache how to fetch your data
const TodoResource = unstable_createResource(fetchTodo);

function Todo(props) {
  // Suspends until the data is in the cache
  const todo = TodoResource.read(props.id);
  return <li>{todo.title}</li>;
}

function App() {
  return (
    // Same Suspense component you already use for code splitting
    // would be able to handle data fetching too.
    <React.Suspense fallback={<Spinner />}>
      <ul>
        {/* Siblings fetch in parallel */}
        <Todo id="1" />
        <Todo id="2" />
      </ul>
    </React.Suspense>
  );
}

// Other libraries like Apollo and Relay can also
// provide Suspense integrations with similar APIs.

There is no official documentation for how to fetch data with Suspense yet, but you can find some early information in this talk and this small demo. We’ll write documentation for React Cache (and how to write your own Suspense-compatible library) closer to this React release, but if you’re curious, you can find its very early source code here.

The low-level Suspense mechanism (suspending rendering and showing a fallback) is expected to be stable even in React 16.6. We’ve used it for code splitting in production for months. However, the higher-level APIs for data fetching are very unstable. React Cache is rapidly changing, and will change at least a few more times. There are some low-level APIs that are missing for a good higher-level API to be possible. We don’t recommend using React Cache anywhere except very early experiments. Note that React Cache itself isn’t strictly tied to React releases, but the current alphas lack basic features as cache invalidation, and you’ll run into a wall very soon. We expect to have something usable with this React release.

Eventually we’d like most data fetching to happen through Suspense but it will take a long time until all integrations are ready. In practice we expect it to be adopted very incrementally, and often through layers like Apollo or Relay rather than directly. Missing higher level APIs aren’t the only obstacle — there are also some important UI patterns we don’t support yet such as showing progress indicator outside of the loading view hierarchy. As always, we will communicate our progress in the release notes on this blog.

Status in React DOM and React Native: Technically, a compatible cache would already work with <React.Suspense> in React 16.6. However, we don’t expect to have a good cache implementation until this React minor release. If you’re feeling adventurous, you can try to write your own cache by looking at the React Cache alphas. However, note that the mental model is sufficiently different that there’s a high risk of misunderstanding it until the docs are ready.

Status in React DOM Server: Suspense is not available in the server renderer yet. As we mentioned earlier, we’ve started work on a new asynchronous server renderer that will support Suspense, but it’s a large project and will take a good chunk of 2019 to complete.

Recommendation: Wait for this minor React release in order to use Suspense for data fetching. Don’t try to use Suspense features in 16.6 for it; it’s not supported. However, your existing <Suspense> components for code splitting will be able to show loading states for data too when Suspense for Data Fetching becomes officially supported.

Other Projects

Modernizing React DOM

We started an investigation into simplifying and modernizing ReactDOM, with a goal of reduced bundle size and aligning closer with the browser behavior. It is still early to say which specific bullet points will “make it” because the project is in an exploratory phase. We will communicate our progress on that issue.

Suspense for Server Rendering

We started designing a new server renderer that supports Suspense (including waiting for asynchronous data on the server without double rendering) and progressively loading and hydrating page content in chunks for best user experience. You can watch an overview of its early prototype in this talk. The new server renderer is going to be our major focus in 2019, but it’s too early to say anything about its release schedule. Its development, as always, will happen on GitHub.

And that’s about it! As you can see, there’s a lot here to keep us busy but we expect much progress in the coming months.

We hope this post gives you an idea of what we’re working on, what you can use today, and what you can expect to use in the future. While there’s a lot of discussion about new features on social media platforms, you won’t miss anything important if you read this blog.

We’re always open to feedback, and love to hear from you in the RFC repository, the issue tracker, and on Twitter.

Sophie Alpert and Dan Abramov kicked off Day 1 with their keynote, React Today and Tomorrow. In the talk, they introduced Hooks, which are a new proposal that adds the ability to access features such as state without writing a JavaScript class. Hooks promise to dramatically simplify the code required for React components and are currently available in a React alpha release.

On the morning of Day 2, Andrew Clark and Brian Vaughn presented Concurrent Rendering in React. Andrew covered the recently announced React.lazy API for code splitting and previewed two upcoming features: concurrent mode and Suspense. Brian demonstrated how to use React’s new profiler tooling to make apps built in React run faster.

In the afternoon, Parashuram N spoke in detail about React Native’s New Architecture, a long-term project that the React Native team has been working on over the past year and announced in June. We’re really excited about the potential of this project to improve performance, simplify interoperability with other libraries, and set a strong foundation for the future of React Native.

Now that the conference is over, all 28 conference talks are available to stream online. There are tons of great ones from both days. We can’t wait until next year!

Check out the full changelog below.

React.memo

Class components can bail out from rendering when their input props are the same using PureComponent or shouldComponentUpdate. Now you can do the same with function components by wrapping them in React.memo.

const MyComponent = React.memo(function MyComponent(props) {
  /* only rerenders if props change */
});

React.lazy: Code-Splitting with Suspense

You may have seen Dan’s talk about React Suspense at JSConf Iceland. Now you can use the Suspense component to do code-splitting by wrapping a dynamic import in a call to React.lazy().

import React, {lazy, Suspense} from 'react';
const OtherComponent = lazy(() => import('./OtherComponent'));

function MyComponent() {
  return (
    <Suspense fallback={<div>Loading...</div>}>
      <OtherComponent />
    </Suspense>
  );
}

The Suspense component will also allow library authors to start building data fetching with Suspense support in the future.

Note: This feature is not yet available for server-side rendering. Suspense support will be added in a later release.

static contextType

In React 16.3 we introduced the official Context API as a replacement to the previous Legacy Context API.

const MyContext = React.createContext();

We’ve heard feedback that adopting the new render prop API can be difficult in class components. So we’ve added a convenience API to consume a context value from within a class component.

class MyClass extends React.Component {
  static contextType = MyContext;
  componentDidMount() {
    let value = this.context;
    /* perform a side-effect at mount using the value of MyContext */
  }
  componentDidUpdate() {
    let value = this.context;
    /* ... */
  }
  componentWillUnmount() {
    let value = this.context;
    /* ... */
  }
  render() {
    let value = this.context;
    /* render something based on the value of MyContext */
  }
}

static getDerivedStateFromError()

React 16 introduced Error Boundaries for handling errors thrown in React renders. We already had the componentDidCatch lifecycle method which gets fired after an error has already happened. It’s great for logging errors to the server. It also lets you show a different UI to the user by calling setState.

Before that is fired, we render null in place of the tree that threw an error. This sometimes breaks parent components that don’t expect their refs to be empty. It also doesn’t work to recover from errors on the server since the Did lifecycle methods don’t fire during server-side rendering.

We’re adding another error method that lets you render the fallback UI before the render completes. See the docs for getDerivedStateFromError().

Note: getDerivedStateFromError() is not yet available for server-side rendering. It is designed to work with server-side rendering in a future release. We’re releasing it early so that you can start preparing to use it.

Deprecations in StrictMode

In 16.3 we introduced the StrictMode component. It lets you opt-in to early warnings for patterns that might cause problems in the future.

We’ve added two more APIs to the list of deprecated APIs in StrictMode. If you don’t use StrictMode you don’t have to worry; these warning won’t fire for you.

• ReactDOM.findDOMNode() - This API is often misunderstood and most uses of it are unnecessary. It can also be surprisingly slow in React 16. See the docs for possible upgrade paths.
• Legacy Context using contextTypes and getChildContext - Legacy context makes React slightly slower and bigger than it needs to be. That’s why we strongly want to encourage upgrading to the new context API. Hopefully the addition of the contextType API makes this a bit easier.

If you’re having trouble upgrading, we’d like to hear your feedback.

Installation

React v16.6.0 is available on the npm registry.

To install React 16 with Yarn, run:

yarn add react@^16.6.0 react-dom@^16.6.0

To install React 16 with npm, run:

npm install --save react@^16.6.0 react-dom@^16.6.0

We also provide UMD builds of React via a CDN:

<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>

Refer to the documentation for detailed installation instructions.

Changelog

React

• Add React.memo() as an alternative to PureComponent for functions. (@acdlite in #13748)
• Add React.lazy() for code splitting components. (@acdlite in #13885)
• React.StrictMode now warns about legacy context API. (@bvaughn in #13760)
• React.StrictMode now warns about findDOMNode. (@sebmarkbage in #13841)
• Rename unstable_AsyncMode to unstable_ConcurrentMode. (@trueadm in #13732)
• Rename unstable_Placeholder to Suspense, and delayMs to maxDuration. (@gaearon in #13799 and @sebmarkbage in #13922)

React DOM

• Add contextType as a more ergonomic way to subscribe to context from a class. (@bvaughn in #13728)
• Add getDerivedStateFromError lifecycle method for catching errors in a future asynchronous server-side renderer. (@bvaughn in #13746)
• Warn when <Context> is used instead of <Context.Consumer>. (@trueadm in #13829)
• Fix gray overlay on iOS Safari. (@philipp-spiess in #13778)
• Fix a bug caused by overwriting window.event in development. (@sergei-startsev in #13697)

React DOM Server

• Add support for React.memo(). (@alexmckenley in #13855)
• Add support for contextType. (@alexmckenley and @sebmarkbage in #13889)

Scheduler (Experimental)

• Rename the package to scheduler. (@gaearon in #13683)
• Support priority levels, continuations, and wrapped callbacks. (@acdlite in #13720 and #13842)
• Improve the fallback mechanism in non-DOM environments. (@acdlite in #13740)
• Schedule requestAnimationFrame earlier. (@acdlite in #13785)
• Fix the DOM detection to be more thorough. (@trueadm in #13731)
• Fix bugs with interaction tracing. (@bvaughn in #13590)
• Add the envify transform to the package. (@mridgway in #13766)

While React itself doesn’t require any build dependencies, it can be challenging to write a complex app without a fast test runner, a production minifier, and a modular codebase. Since the very first release, the goal of Create React App has been to help you focus on what matters the most — your application code — and to handle build and testing setup for you.

Many of the tools it relies on have since released new versions containing new features and performance improvements: Babel 7, webpack 4, and Jest 23. However, updating them manually and making them work well together takes a lot of effort. And this is exactly what Create React App 2.0 contributors have been busy with for the past few months: migrating the configuration and dependencies so that you don’t need to do it yourself.

Now that Create React App 2.0 is out of beta, let’s see what’s new and how you can try it!

Note

Don’t feel pressured to upgrade anything. If you’re satisfied with the current feature set, its performance, and reliability, you can keep using the version you’re currently at! It might also be a good idea to let the 2.0 release stabilize a little bit before switching to it in production.

What’s New

Here’s a short summary of what’s new in this release:

• 🎉 More styling options: you can use Sass and CSS Modules out of the box.
• 🐠 We updated to Babel 7, including support for the React fragment syntax and many bugfixes.
• 📦 We updated to webpack 4, which automatically splits JS bundles more intelligently.
• 🃏 We updated to Jest 23, which includes an interactive mode for reviewing snapshots.
• 💄 We added PostCSS so you can use new CSS features in old browsers.
• 💎 You can use Apollo, Relay Modern, MDX, and other third-party Babel Macros transforms.
• 🌠 You can now import an SVG as a React component, and use it in JSX.
• 🐈 You can try the experimental Yarn Plug’n’Play mode that removes node_modules.
• 🕸 You can now plug your own proxy implementation in development to match your backend API.
• 🚀 You can now use packages written for latest Node versions without breaking the build.
• ✂️ You can now optionally get a smaller CSS bundle if you only plan to target modern browsers.
• 👷‍♀️ Service workers are now opt-in and are built using Google’s Workbox.

All of these features work out of the box — to enable them, follow the below instructions.

Starting a Project with Create React App 2.0

You don’t need to update anything special. Starting from today, when you run create-react-app it will use the 2.0 version of the template by default. Have fun!

If you want to use the old 1.x template for some reason, you can do that by passing --scripts-version=react-scripts@1.x as an argument to create-react-app.

Updating a Project to Create React App 2.0

Upgrading a non-ejected project to Create React App 2.0 should usually be straightforward. Open package.json in the root of your project and find react-scripts there.

Then change its version to 2.0.3:

  // ... other dependencies ...
  "react-scripts": "2.0.3"

Run npm install (or yarn, if you use it). For many projects, this one-line change is sufficient to upgrade!

working here... thanks for all the new functionality 👍

— Stephen Haney (@sdothaney) October 1, 2018

Here are a few more tips to get you started.

When you run npm start for the first time after the upgrade, you’ll get a prompt asking about which browsers you’d like to support. Press y to accept the default ones. They’ll be written to your package.json and you can edit them any time. Create React App will use this information to produce smaller or polyfilled CSS bundles depending on whether you target modern browsers or older browsers.

If npm start still doesn’t quite work for you after the upgrade, check out the more detailed migration instructions in the release notes. There are a few breaking changes in this release but the scope of them is limited, so they shouldn’t take more than a few hours to sort out. Note that support for older browsers is now opt-in to reduce the polyfill size.

If you previously ejected but now want to upgrade, one common solution is to find the commits where you ejected (and any subsequent commits changing the configuration), revert them, upgrade, and later optionally eject again. It’s also possible that the feature you ejected for (maybe Sass or CSS Modules?) is now supported out of the box.

Note

Due to a possible bug in npm, you might see warnings about unsatisfied peer dependencies. You should be able to ignore them. As far as we’re aware, this issue isn’t present with Yarn.

Breaking Changes

Here’s a short list of breaking changes in this release:

• Node 6 is no longer supported.
• Support for older browsers (such as IE 9 to IE 11) is now opt-in with a separate package.
• Code-splitting with import() now behaves closer to specification, while require.ensure() is disabled.
• The default Jest environment now includes jsdom.
• Support for specifying an object as proxy setting was replaced with support for a custom proxy module.
• Support for .mjs extension was removed until the ecosystem around it stabilizes.
• PropTypes definitions are automatically stripped out of the production builds.

If either of these points affects you, 2.0.3 release notes contain more detailed instructions.

Learn More

You can find the full changelog in the release notes. This was a large release, and we may have missed something. Please report any problems to our issue tracker and we’ll try to help.

Note

If you’ve been using 2.x alpha versions, we provide separate migration instructions for them.

Thanks

This release wouldn’t be possible without our wonderful community of contributors. We’d like to thank Andreas Cederström, Clement Hoang, Brian Ng, Kent C. Dodds, Ade Viankakrisna Fadlil, Andrey Sitnik, Ro Savage, Fabiano Brito, Ian Sutherland, Pete Nykänen, Jeffrey Posnick, Jack Zhao, Tobias Koppers, Henry Zhu, Maël Nison, XiaoYan Li, Marko Trebizan, Marek Suscak, Mikhail Osher, and many others who provided feedback and testing for this release.

This blog post covers the following topics:

• Profiling an application

• Reading performance data

  • Browsing commits
  • Filtering commits
  • Flame chart
  • Ranked chart
  • Component chart
  • Interactions

• Troubleshooting

  • No profiling data has been recorded for the selected root
  • No timing data to display for the selected commit
• Deep dive video

Profiling an application

DevTools will show a “Profiler” tab for applications that support the new profiling API:

Note:

react-dom 16.5+ supports profiling in DEV mode. A production profiling bundle is also available as react-dom/profiling. Read more about how to use this bundle at fb.me/react-profiling

The “Profiler” panel will be empty initially. Click the record button to start profiling:

Once you’ve started recording, DevTools will automatically collect performance information each time your application renders. Use your app as you normally would. When you are finished profiling, click the “Stop” button.

Assuming your application rendered at least once while profiling, DevTools will show several ways to view the performance data. We’ll take a look at each of these below.

Reading performance data

Browsing commits

Conceptually, React does work in two phases:

• The render phase determines what changes need to be made to e.g. the DOM. During this phase, React calls render and then compares the result to the previous render.
• The commit phase is when React applies any changes. (In the case of React DOM, this is when React inserts, updates, and removes DOM nodes.) React also calls lifecycles like componentDidMount and componentDidUpdate during this phase.

The DevTools profiler groups performance info by commit. Commits are displayed in a bar chart near the top of the profiler:

Each bar in the chart represents a single commit with the currently selected commit colored black. You can click on a bar (or the left/right arrow buttons) to select a different commit.

The color and height of each bar corresponds to how long that commit took to render. (Taller, yellow bars took longer than shorter, blue bars.)

Filtering commits

The longer you profile, the more times your application will render. In some cases you may end up with too many commits to easily process. The profiler offers a filtering mechanism to help with this. Use it to specify a threshold and the profiler will hide all commits that were faster than that value.

Flame chart

The flame chart view represents the state of your application for a particular commit. Each bar in the chart represents a React component (e.g. App, Nav). The size and color of the bar represents how long it took to render the component and its children. (The width of a bar represents how much time was spent when the component last rendered and the color represents how much time was spent as part of the current commit.)

Note:

The width of a bar indicates how long it took to render the component (and its children) when they last rendered. If the component did not re-render as part of this commit, the time represents a previous render. The wider a component is, the longer it took to render.

The color of a bar indicates how long the component (and its children) took to render in the selected commit. Yellow components took more time, blue components took less time, and gray components did not render at all during this commit.

For example, the commit shown above took a total of 18.4ms to render. The Router component was the “most expensive” to render (taking 18.4ms). Most of this time was due to two of its children, Nav (8.4ms) and Route (7.9ms). The rest of the time was divided between its remaining children or spent in the component’s own render method.

You can zoom in or out on a flame chart by clicking on components:

Clicking on a component will also select it and show information in the right side panel which includes its props and state at the time of this commit. You can drill into these to learn more about what the component actually rendered during the commit:

In some cases, selecting a component and stepping between commits may also provide a hint as to why the component rendered:

The above image shows that state.scrollOffset changed between commits. This is likely what caused the List component to re-render.

Ranked chart

The ranked chart view represents a single commit. Each bar in the chart represents a React component (e.g. App, Nav). The chart is ordered so that the components which took the longest to render are at the top.

Note:

A component’s render time includes the time spent rendering its children, so the components which took the longest to render are generally near the top of the tree.

As with the flame chart, you can zoom in or out on a ranked chart by clicking on components.

Component chart

Sometimes it’s useful to see how many times a particular component rendered while you were profiling. The component chart provides this information in the form of a bar chart. Each bar in the chart represents a time when the component rendered. The color and height of each bar corresponds to how long the component took to render relative to other components in a particular commit.

The chart above shows that the List component rendered 11 times. It also shows that each time it rendered, it was the most “expensive” component in the commit (meaning that it took the longest).

To view this chart, either double-click on a component or select a component and click on the blue bar chart icon in the right detail pane. You can return to the previous chart by clicking the “x” button in the right detail pane. You can also double click on a particular bar to view more information about that commit.

If the selected component did not render at all during the profiling session, the following message will be shown:

Interactions

React recently added another experimental API for tracing the cause of an update. “Interactions” traced with this API will also be shown in the profiler:

The image above shows a profiling session that traced four interactions. Each row represents an interaction that was traced. The colored dots along the row represent commits that were related to that interaction.

You can also see which interactions were traced for a particular commit from the flame chart and ranked chart views as well:

You can navigate between interactions and commits by clicking on them:

The tracing API is still new and we will cover it in more detail in a future blog post.

Troubleshooting

No profiling data has been recorded for the selected root

If your application has multiple “roots”, you may see the following message after profiling:

This message indicates that no performance data was recorded for the root that’s selected in the “Elements” panel. In this case, try selecting a different root in that panel to view profiling information for that root:

No timing data to display for the selected commit

Sometimes a commit may be so fast that performance.now() doesn’t give DevTools any meaningful timing information. In this case, the following message will be shown:

Deep dive video

The following video demonstrates how the React profiler can be used to detect and improve performance bottlenecks in an actual React application.

Short Description

Today, we are releasing a fix for a vulnerability we discovered in the react-dom/server implementation. It was introduced with the version 16.0.0 and has existed in all subsequent releases until today.

This vulnerability can only affect some server-rendered React apps. Purely client-rendered apps are not affected. Additionally, we expect that most server-rendered apps don’t contain the vulnerable pattern described below. Nevertheless, we recommend to follow the mitigation instructions at the earliest opportunity.

While we were investigating this vulnerability, we found similar vulnerabilities in a few other popular front-end libraries. We have coordinated this release together with Vue and Preact releases fixing the same issue. The tracking number for this vulnerability is CVE-2018-6341.

Mitigation

We have prepared a patch release with a fix for every affected minor version.

16.0.x

If you’re using react-dom/server with this version:

• react-dom@16.0.0

Update to this version instead:

• react-dom@16.0.1 (contains the mitigation)

16.1.x

If you’re using react-dom/server with one of these versions:

• react-dom@16.1.0
• react-dom@16.1.1

Update to this version instead:

• react-dom@16.1.2 (contains the mitigation)

16.2.x

If you’re using react-dom/server with this version:

• react-dom@16.2.0

Update to this version instead:

• react-dom@16.2.1 (contains the mitigation)

16.3.x

If you’re using react-dom/server with one of these versions:

• react-dom@16.3.0
• react-dom@16.3.1
• react-dom@16.3.2

Update to this version instead:

• react-dom@16.3.3 (contains the mitigation)

16.4.x

If you’re using react-dom/server with one of these versions:

• react-dom@16.4.0
• react-dom@16.4.1

Update to this version instead:

• react-dom@16.4.2 (contains the mitigation)

If you’re using a newer version of react-dom, no action is required.

Note that only the react-dom package needs to be updated.

Detailed Description

Your app might be affected by this vulnerability only if both of these two conditions are true:

• Your app is being rendered to HTML using ReactDOMServer API, and
• Your app includes a user-supplied attribute name in an HTML tag.

Specifically, the vulnerable pattern looks like this:

let props = {};
props[userProvidedData] = "hello";
let element = <div {...props} />;
let html = ReactDOMServer.renderToString(element);

In order to exploit it, the attacker would need to craft a special attribute name that triggers an XSS vulnerability. For example:

let userProvidedData = '></div><script>alert("hi")</script>';

In the vulnerable versions of react-dom/server, the output would let the attacker inject arbitrary markup:

<div ></div><script>alert("hi")</script>

In the versions after the vulnerability was fixed (and before it was introduced), attributes with invalid names are skipped:

<div></div>

You would also see a warning about an invalid attribute name.

Note that we expect attribute names based on user input to be very rare in practice. It doesn’t serve any common practical use case, and has other potential security implications that React can’t guard against.

Installation

React v16.4.2 is available on the npm registry.

To install React 16 with Yarn, run:

yarn add react@^16.4.2 react-dom@^16.4.2

To install React 16 with npm, run:

npm install --save react@^16.4.2 react-dom@^16.4.2

We also provide UMD builds of React via a CDN:

<script crossorigin src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
<script crossorigin src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>

Refer to the documentation for detailed installation instructions.

Changelog

React DOM Server

• Fix a potential XSS vulnerability when the attacker controls an attribute name (CVE-2018-6341). This fix is available in the latest react-dom@16.4.2, as well as in previous affected minor versions: react-dom@16.0.1, react-dom@16.1.2, react-dom@16.2.1, and react-dom@16.3.3. (@gaearon in #13302)

• Fix a crash in the server renderer when an attribute is called hasOwnProperty. This fix is only available in react-dom@16.4.2. (@gaearon in #13303)

For a long time, the lifecycle componentWillReceiveProps was the only way to update state in response to a change in props without an additional render. In version 16.3, we introduced a replacement lifecycle, getDerivedStateFromProps to solve the same use cases in a safer way. At the same time, we’ve realized that people have many misconceptions about how to use both methods, and we’ve found anti-patterns that result in subtle and confusing bugs. The getDerivedStateFromProps bugfix in 16.4 makes derived state more predictable, so the results of misusing it are easier to notice.

Note

All of the anti-patterns described in this post apply to both the older componentWillReceiveProps and the newer getDerivedStateFromProps.

This blog post will cover the following topics:

• When to use derived state

• Common bugs when using derived state

  • Anti-pattern: Unconditionally copying props to state
  • Anti-pattern: Erasing state when props change
• Preferred solutions
• What about memoization?

When to Use Derived State

getDerivedStateFromProps exists for only one purpose. It enables a component to update its internal state as the result of changes in props. Our previous blog post provided some examples, like recording the current scroll direction based on a changing offset prop or loading external data specified by a source prop.

We did not provide many examples, because as a general rule, derived state should be used sparingly. All problems with derived state that we have seen can be ultimately reduced to either (1) unconditionally updating state from props or (2) updating state whenever props and state don’t match. (We’ll go over both in more detail below.)

• If you’re using derived state to memoize some computation based only on the current props, you don’t need derived state. See What about memoization? below.
• If you’re updating derived state unconditionally or updating it whenever props and state don’t match, your component likely resets its state too frequently. Read on for more details.

Common Bugs When Using Derived State

The terms “controlled” and “uncontrolled” usually refer to form inputs, but they can also describe where any component’s data lives. Data passed in as props can be thought of as controlled (because the parent component controls that data). Data that exists only in internal state can be thought of as uncontrolled (because the parent can’t directly change it).

The most common mistake with derived state is mixing these two; when a derived state value is also updated by setState calls, there isn’t a single source of truth for the data. The external data loading example mentioned above may sound similar, but it’s different in a few important ways. In the loading example, there is a clear source of truth for both the “source” prop and the “loading” state. When the source prop changes, the loading state should always be overridden. Conversely, the state is overridden only when the prop changes and is otherwise managed by the component.

Problems arise when any of these constraints are changed. This typically comes in two forms. Let’s take a look at both.

Anti-pattern: Unconditionally copying props to state

A common misconception is that getDerivedStateFromProps and componentWillReceiveProps are only called when props “change”. These lifecycles are called any time a parent component rerenders, regardless of whether the props are “different” from before. Because of this, it has always been unsafe to unconditionally override state using either of these lifecycles. Doing so will cause state updates to be lost.

Let’s consider an example to demonstrate the problem. Here is a EmailInput component that “mirrors” an email prop in state:

class EmailInput extends Component {
  state = { email: this.props.email };

  render() {
    return <input onChange={this.handleChange} value={this.state.email} />;
  }

  handleChange = event => {
    this.setState({ email: event.target.value });
  };

  componentWillReceiveProps(nextProps) {
    // This will erase any local state updates!
    // Do not do this.
    this.setState({ email: nextProps.email });
  }
}

At first, this component might look okay. State is initialized to the value specified by props and updated when we type into the <input>. But if our component’s parent rerenders, anything we’ve typed into the <input> will be lost! (See this demo for an example.) This holds true even if we were to compare nextProps.email !== this.state.email before resetting.

In this simple example, adding shouldComponentUpdate to rerender only when the email prop has changed could fix this. However in practice, components usually accept multiple props; another prop changing would still cause a rerender and improper reset. Function and object props are also often created inline, making it hard to implement a shouldComponentUpdate that reliably returns true only when a material change has happened. Here is a demo that shows that happening. As a result, shouldComponentUpdate is best used as a performance optimization, not to ensure correctness of derived state.

Hopefully it’s clear by now why it is a bad idea to unconditionally copy props to state. Before reviewing possible solutions, let’s look at a related problematic pattern: what if we were to only update the state when the email prop changes?

Anti-pattern: Erasing state when props change

Continuing the example above, we could avoid accidentally erasing state by only updating it when props.email changes:

class EmailInput extends Component {
  state = {
    email: this.props.email
  };

  componentWillReceiveProps(nextProps) {
    // Any time props.email changes, update state.
    if (nextProps.email !== this.props.email) {
      this.setState({
        email: nextProps.email
      });
    }
  }
  
  // ...
}

Note

Even though the example above shows componentWillReceiveProps, the same anti-pattern applies to getDerivedStateFromProps.

We’ve just made a big improvement. Now our component will erase what we’ve typed only when the props actually change.

There is still a subtle problem. Imagine a password manager app using the above input component. When navigating between details for two accounts with the same email, the input would fail to reset. This is because the prop value passed to the component would be the same for both accounts! This would be a surprise to the user, as an unsaved change to one account would appear to affect other accounts that happened to share the same email. (See demo here.)

This design is fundamentally flawed, but it’s also an easy mistake to make. (I’ve made it myself!) Fortunately there are two alternatives that work better. The key to both is that for any piece of data, you need to pick a single component that owns it as the source of truth, and avoid duplicating it in other components. Let’s take a look at each of the alternatives.

Preferred Solutions

Recommendation: Fully controlled component

One way to avoid the problems mentioned above is to remove state from our component entirely. If the email address only exists as a prop, then we don’t have to worry about conflicts with state. We could even convert EmailInput to a lighter-weight function component:

function EmailInput(props) {
  return <input onChange={props.onChange} value={props.email} />;
}

This approach simplifies the implementation of our component, but if we still want to store a draft value, the parent form component will now need to do that manually. (Click here to see a demo of this pattern.)

Recommendation: Fully uncontrolled component with a key

Another alternative would be for our component to fully own the “draft” email state. In that case, our component could still accept a prop for the initial value, but it would ignore subsequent changes to that prop:

class EmailInput extends Component {
  state = { email: this.props.defaultEmail };

  handleChange = event => {
    this.setState({ email: event.target.value });
  };

  render() {
    return <input onChange={this.handleChange} value={this.state.email} />;
  }
}

In order to reset the value when moving to a different item (as in our password manager scenario), we can use the special React attribute called key. When a key changes, React will create a new component instance rather than update the current one. Keys are usually used for dynamic lists but are also useful here. In our case, we could use the user ID to recreate the email input any time a new user is selected:

<EmailInput
  defaultEmail={this.props.user.email}
  key={this.props.user.id}
/>

Each time the ID changes, the EmailInput will be recreated and its state will be reset to the latest defaultEmail value. (Click here to see a demo of this pattern.) With this approach, you don’t have to add key to every input. It might make more sense to put a key on the whole form instead. Every time the key changes, all components within the form will be recreated with a freshly initialized state.

In most cases, this is the best way to handle state that needs to be reset.

Note

While this may sound slow, the performance difference is usually insignificant. Using a key can even be faster if the components have heavy logic that runs on updates since diffing gets bypassed for that subtree.

Alternative 1: Reset uncontrolled component with an ID prop

If key doesn’t work for some reason (perhaps the component is very expensive to initialize), a workable but cumbersome solution would be to watch for changes to “userID” in getDerivedStateFromProps:

class EmailInput extends Component {
  state = {
    email: this.props.defaultEmail,
    prevPropsUserID: this.props.userID
  };

  static getDerivedStateFromProps(props, state) {
    // Any time the current user changes,
    // Reset any parts of state that are tied to that user.
    // In this simple example, that's just the email.
    if (props.userID !== state.prevPropsUserID) {
      return {
        prevPropsUserID: props.userID,
        email: props.defaultEmail
      };
    }
    return null;
  }

  // ...
}

This also provides the flexibility to only reset parts of our component’s internal state if we so choose. (Click here to see a demo of this pattern.)

Note

Even though the example above shows getDerivedStateFromProps, the same technique can be used with componentWillReceiveProps.

Alternative 2: Reset uncontrolled component with an instance method

More rarely, you may need to reset state even if there’s no appropriate ID to use as key. One solution is to reset the key to a random value or autoincrementing number each time you want to reset. One other viable alternative is to expose an instance method to imperatively reset the internal state:

class EmailInput extends Component {
  state = {
    email: this.props.defaultEmail
  };

  resetEmailForNewUser(newEmail) {
    this.setState({ email: newEmail });
  }

  // ...
}

The parent form component could then use a ref to call this method. (Click here to see a demo of this pattern.)

Refs can be useful in certain cases like this one, but generally we recommend you use them sparingly. Even in the demo, this imperative method is nonideal because two renders will occur instead of one.

Recap

To recap, when designing a component, it is important to decide whether its data will be controlled or uncontrolled.

Instead of trying to “mirror” a prop value in state, make the component controlled, and consolidate the two diverging values in the state of some parent component. For example, rather than a child accepting a “committed” props.value and tracking a “draft” state.value, have the parent manage both state.draftValue and state.committedValue and control the child’s value directly. This makes the data flow more explicit and predictable.

For uncontrolled components, if you’re trying to reset state when a particular prop (usually an ID) changes, you have a few options:

• Recommendation: To reset all internal state, use the key attribute.
• Alternative 1: To reset only certain state fields, watch for changes in a special property (e.g. props.userID).
• Alternative 2: You can also consider fall back to an imperative instance method using refs.

What about memoization?

We’ve also seen derived state used to ensure an expensive value used in render is recomputed only when the inputs change. This technique is known as memoization.

Using derived state for memoization isn’t necessarily bad, but it’s usually not the best solution. There is inherent complexity in managing derived state, and this complexity increases with each additional property. For example, if we add a second derived field to our component state then our implementation would need to separately track changes to both.

Let’s look at an example of one component that takes one prop—a list of items—and renders the items that match a search query entered by the user. We could use derived state to store the filtered list:

class Example extends Component {
  state = {
    filterText: "",
  };

  // *******************************************************
  // NOTE: this example is NOT the recommended approach.
  // See the examples below for our recommendations instead.
  // *******************************************************

  static getDerivedStateFromProps(props, state) {
    // Re-run the filter whenever the list array or filter text change.
    // Note we need to store prevPropsList and prevFilterText to detect changes.
    if (
      props.list !== state.prevPropsList ||
      state.prevFilterText !== state.filterText
    ) {
      return {
        prevPropsList: props.list,
        prevFilterText: state.filterText,
        filteredList: props.list.filter(item => item.text.includes(state.filterText))
      };
    }
    return null;
  }

  handleChange = event => {
    this.setState({ filterText: event.target.value });
  };

  render() {
    return (
      <Fragment>
        <input onChange={this.handleChange} value={this.state.filterText} />
        <ul>{this.state.filteredList.map(item => <li key={item.id}>{item.text}</li>)}</ul>
      </Fragment>
    );
  }
}

This implementation avoids recalculating filteredList more often than necessary. But it is more complicated than it needs to be, because it has to separately track and detect changes in both props and state in order to properly update the filtered list. In this example, we could simplify things by using PureComponent and moving the filter operation into the render method:

// PureComponents only rerender if at least one state or prop value changes.
// Change is determined by doing a shallow comparison of state and prop keys.
class Example extends PureComponent {
  // State only needs to hold the current filter text value:
  state = {
    filterText: ""
  };

  handleChange = event => {
    this.setState({ filterText: event.target.value });
  };

  render() {
    // The render method on this PureComponent is called only if
    // props.list or state.filterText has changed.
    const filteredList = this.props.list.filter(
      item => item.text.includes(this.state.filterText)
    )

    return (
      <Fragment>
        <input onChange={this.handleChange} value={this.state.filterText} />
        <ul>{filteredList.map(item => <li key={item.id}>{item.text}</li>)}</ul>
      </Fragment>
    );
  }
}

The above approach is much cleaner and simpler than the derived state version. Occasionally, this won’t be good enough—filtering may be slow for large lists, and PureComponent won’t prevent rerenders if another prop were to change. To address both of these concerns, we could add a memoization helper to avoid unnecessarily re-filtering our list:

import memoize from "memoize-one";

class Example extends Component {
  // State only needs to hold the current filter text value:
  state = { filterText: "" };

  // Re-run the filter whenever the list array or filter text changes:
  filter = memoize(
    (list, filterText) => list.filter(item => item.text.includes(filterText))
  );

  handleChange = event => {
    this.setState({ filterText: event.target.value });
  };

  render() {
    // Calculate the latest filtered list. If these arguments haven't changed
    // since the last render, `memoize-one` will reuse the last return value.
    const filteredList = this.filter(this.props.list, this.state.filterText);

    return (
      <Fragment>
        <input onChange={this.handleChange} value={this.state.filterText} />
        <ul>{filteredList.map(item => <li key={item.id}>{item.text}</li>)}</ul>
      </Fragment>
    );
  }
}

This is much simpler and performs just as well as the derived state version!

When using memoization, remember a couple of constraints:

1. In most cases, you’ll want to attach the memoized function to a component instance. This prevents multiple instances of a component from resetting each other’s memoized keys.
2. Typically you’ll want to use a memoization helper with a limited cache size in order to prevent memory leaks over time. (In the example above, we used memoize-one because it only caches the most recent arguments and result.)
3. None of the implementations shown in this section will work if props.list is recreated each time the parent component renders. But in most cases, this setup is appropriate.

In closing

In real world applications, components often contain a mix of controlled and uncontrolled behaviors. This is okay! If each value has a clear source of truth, you can avoid the anti-patterns mentioned above.

It is also worth re-iterating that getDerivedStateFromProps (and derived state in general) is an advanced feature and should be used sparingly because of this complexity. If your use case falls outside of these patterns, please share it with us on GitHub or Twitter!