React v16.0

October 26, 2017 by Andrew Clark

We’re excited to announce the release of React v16.0! Among the changes are some long-standing feature requests, including fragments, error boundaries, portals, support for custom DOM attributes, improved server-side rendering, and reduced file size.

New render return types: fragments and strings

You can now return an array of elements from a component’s render method:

render() {
  // No need to wrap list items in an extra element!
  return [
    // Don't forget the keys :)
    <li key="A"/>First item</li>,
    <li key="B"/>Second item</li>,
    <li key="C"/>Third item</li>,

Support for returning strings from the render method has also been added.

API Documentation

Better error handling

Previously, runtime errors during rendering could potentially put React in a broken state, producing cryptic error messages and requiring a page refresh to recover. To address this problem, React 16 uses a more resilient error-handling strategy. By default, if an error is thrown inside a component’s render or lifecycle methods, the whole component tree is unmounted from the root. This prevents the display of corrupted data. However, it’s probably not the ideal user experience.

Instead of unmounting the whole app every time there’s an error, you can use error boundaries. Error boundaries are special components that capture errors inside their subtree and display a fallback UI in its place. Think of error boundaries like try-catch statements, but for React components.

For more details, check out our previous post on error handling in React 16.


Portals provide a first-class way to render children into a DOM node that exists outside the DOM hierarchy of the parent component.

render() {
  // React does *not* create a new div. It renders the children into `divNode`.
  // `divNode` is any valid DOM node, regardless of its location in the DOM.
  return React.createPortal(

See a full example in the documentation for portals

Better server-side rendering

React 16 is better at hydrating server-rendered HTML. It no longer requires the initial render to exactly match the result from the server. Instead, it will attempt to reuse as much of the existing DOM as possible. No more checksums!

The server renderer has also been completely rewritten to support streaming. React core team member Sasha Aicken, who worked on this feature, wrote a great article describing React 16’s SSR improvements. “Rendering to a stream can reduce the time to first byte (TTFB) for your content, sending the beginning of the document down the wire to the browser before the next part of the document has even been generated. All major browsers will start parsing and rendering the document earlier when the content is streamed from the server this way.”

Support for custom DOM attributes

Instead of ignoring unrecognized HTML and SVG attributes, React will now pass them through to the DOM. This has the added benefit of allowing us to get rid of most of React’s attribute whitelist, resulting in reduced file sizes.

Reduced file size

Despite all these additions, React 16 is actually smaller compared to 15.6.1!

  • react is 5.3 kb (2.2 kb gzipped), down from 20.7 kb (6.9 kb gzipped).
  • react-dom is 103.7 kb (32.6 kb gzipped), down from 141 kb (42.9 kb gzipped).
  • react + react-dom is 109 kb (34.8 kb gzipped), down from 161.7 kb (49.8 kb gzipped).

That amounts to a combined 32% size decrease compared to the previous version (30% post-gzip).

The size difference is partly attributable to a change in packaging. React now uses Rollup to create flat bundles for each of its different target formats, resulting in both size and runtime performance wins. The

New core architecture

React 16 is the first version of React built on top of a new core architecture, codenamed “Fiber.” You can read all about this project over on Facebook’s engineering blog (TODO: link). (Spoiler: we rewrote React!)

Most of the features in this release, like error boundaries and fragments, were made possible by the rewritten core. Over the next few releases, you can expect more new features as we begin to unlock the full potential of React.

Perhaps the most exciting area we’re working on is async rendering—a strategy for cooperatively scheduling rendering work by periodically yielding execution to the browser. The upshot is that, with async rendering, apps are more responsive because React avoids blocking the main thread.

See this demo for an early peek at the types of problems async rendering can solve. TODO: link to demo.

We think async rendering is a big deal, and represents the future of React. To make migration to v16.0 as smooth as possible, we’re not enabling any async features yet, but we’re excited to roll this out in the coming months. Stay tuned!


Although React 16 includes significant internal changes, in terms of upgrading, you can think of this like any other major React release. We’ve been serving React 16 to Facebook and users since earlier this year, and we released several beta and release candidate versions to flush out additional issues. With minor exceptions, if your app runs in 15.6 without any warnings, it should work in 16.


Hydrating a server-rendered container now has an explicit API. Use ReactDOM.hydrate instead of ReactDOM.render if you’re reviving server-rendered HTML. Keep using ReactDOM.render if you’re just doing client-side rendering.

Documentation (TODO: link)

Breaking changes

  • React 15 had limited, undocumented support for error boundaries using unstable_handleError. This method has been renamed to componentDidCatch. You can use a codemod to automatically migrate to the new API.
  • ReactDOM.render and ReactDOM.unstable_renderIntoContainer now return null if called from inside a lifecycle method. To work around this, you can use portals or [refs[(
  • setState:

    • Calling setState with null no longer triggers an update. This allows you to decide in an updater function if you want to re-render.
    • Calling setState directly in render always causes an update. This was not previously the case. Regardless, you should not be calling setState from render.
    • setState callbacks (second argument) now fire immediately after componentDidMount / componentDidUpdate instead of after all components have rendered.
  • When replacing <A /> with <B />, B.componentWillMount now always happens before A.componentWillUnmount. Previously, A.componentWillUnmount could fire first in some cases.
  • Previously, changing the ref to a component would always detach the ref before that component’s render is called. Now, we change the ref later, when applying the changes to the DOM.
  • It is not safe to re-render into a container that was modified by something other than React. This worked previously in some cases but was never supported. We now emit a warning in this case. Instead you should clean up your component trees using ReactDOM.unmountComponentAtNode. See this example.
  • componentDidUpdate lifecycle no longer receives prevContext param. (See #8631)
  • Shallow renderer no longer calls componentDidUpdate() because DOM refs are not available. This also makes it consistent with componentDidMount() (which does not get called in previous versions either).
  • Shallow renderer does not implement unstable_batchedUpdates() anymore.


  • There is no react/lib/* and react-dom/lib/* anymore. Even in CommonJS environments, React and ReactDOM are precompiled to single files (“flat bundles”). If you previously relied on undocumented React internals, and they don’t work anymore, let us know about your specific case in this issue, and we’ll try to figure out a migration strategy for you.
  • There is no react-with-addons.js build anymore. All compatible addons are published separately on npm, and have single-file browser versions if you need them.
  • The deprecations introduced in 15.x have been removed from the core package. React.createClass is now available as create-react-class, React.PropTypes as prop-types, React.DOM as react-dom-factories, react-addons-test-utils as react-dom/test-utils, and shallow renderer as react-test-renderer/shallow. See 15.5.0 and 15.6.0 blog posts for instructions on migrating code and automated codemods.
  • The names and paths to the single-file browser builds have changed to emphasize the difference between development and production builds. For example:

    • react/dist/react.jsreact/umd/react.development.js
    • react/dist/react.min.jsreact/umd/react.production.min.js
    • react-dom/dist/react-dom.jsreact-dom/umd/react-dom.development.js
    • react-dom/dist/react-dom.min.js → react-dom/umd/react-dom.production.min.js

JavaScript environment requirements

TODO: inline JavaScript environment requirements doc


As always, this release would not have been possible without our open source contributors. Thanks to everyone who filed bugs, opened PRs, responded to issues, wrote documentation, and more!

Special thanks to the following core team members: TODO