The third React 16 RC is now available for public testing. 🎉

Installation Instructions

The RC has been published to NPM with the tag "next". Regular NPM installs will continue to use the 15.6 release. To install the RC use:

yarn add react@next react-dom@next

Or:

npm install --save react@next react-dom@next

What Does React 16 Mean for You?

React 16 is the first release that ships with a rewrite of the React core (previously codenamed “Fiber”). This rewrite had a few goals:

• Remove old internal abstractions that didn’t age well and hindered internal changes.
• Let us ship some of the most requested features like returning arrays from render, recovering from component errors, and readable component stack traces for every error.
• Enable us to start experimenting with asynchronous rendering of components for better perceived performance.

This initial React 16.0 release is mostly focused on compatibility with existing apps. It does not enable asynchronous rendering yet. We will introduce an opt-in to the async mode later during React 16.x. We don’t expect React 16.0 to make your apps significantly faster or slower, but we’d love to know if you see improvements or regressions.

JavaScript Environment Requirements

React 16 depends on the collection types Map and Set. If you support older browsers and devices which may not yet provide these natively (eg <IE11), consider including a global polyfill in your bundled application, such as core-js or babel-polyfill.

A polyfilled environment for React 16 using core-js to support older browsers might look like:

import 'core-js/es6/map';
import 'core-js/es6/set';

import React from 'react';
import ReactDOM from 'react-dom';

ReactDOM.render(
  <h1>Hello, world!</h1>,
  document.getElementById('root')
);

React also depends on requestAnimationFrame (even in test environments). A simple shim for testing environments would be:

global.requestAnimationFrame = function(callback) {
  setTimeout(callback, 0);
};

Points of Interest

• This is a complete rewrite of React but we expect it to work with your existing code. If you fixed all deprecation warnings introduced in 15.x, the 16 beta should work for you.
• Third party libraries that relied on deprecated or unsupported APIs may need updates to work correctly with this new release. Now is a good time to file issues against libraries that have problems. (And tell us if we broke something!)
• We are particularly interested in hearing about performance differences you notice between 15.x and 16.x. We don't expect any massive changes but would love to know about improvements or regressions. Please report them here!
• The server renderer has been completely rewritten, and now offers a streaming mode (ReactDOMServer.renderToNodeStream() and ReactDOMServer.renderToStaticNodeStream()). Server rendering does not use markup validation anymore, and instead tries its best to attach to existing DOM, warning about inconsistencies. And there is no data-reactid anymore! This server renderer code is still very new, so it is likely to have issues. Please report them.
• 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.
• React Native follows a different release cycle and will update to the beta in a future release. (It's already using an alpha release but not yet using Fiber.)

Breaking Changes

Error Handling

• Previously, runtime errors used to put React into a broken state and produce cryptic errors. React 16 fixes this by introducing a special kind of components called “error boundaries”. Error boundaries can catch runtime errors in a component tree, log them, and display a fallback UI instead.
• If there is an uncaught error in a component, and there is no error boundary up in the tree, the whole component tree will be unmounted. This helps avoid very nasty bugs where the UI has been corrupted due to an error, but it means that you need to add a few error boundaries to your app to handle the errors gracefully.
• React 15 had a very limited undocumented support for error boundaries with a different method name. It used to be called unstable_handleError, but has been renamed to componentDidCatch.

You can learn more about the new error handling behavior here.

Scheduling and Lifecycle

• ReactDOM.render() and ReactDOM.unstable_renderIntoContainer() now return null if called from inside a lifecycle method.
  • To work around this, you can either use the new portal API 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 callback (second argument) now fires 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 Pass prevContext param to componentDidUpdate #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.

Packaging

• 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.js → react/umd/react.development.js
  • react/dist/react.min.js → react/umd/react.production.min.js
  • react-dom/dist/react-dom.js → react-dom/umd/react-dom.development.js
  • react-dom/dist/react-dom.min.js → react-dom/umd/react-dom.production.min.js

Known Issues

• The server renderer crashes in production with inline styles. (React 16 server renderer breaks with style object in prod mode #10299, fixed by Fix ReactPartialRenderer in production #10300)
  • Fixed in 16.0.0-beta.2
• The server renderer doesn't yet support returning arrays and strings from components.
  • Fixed in 16.0.0-beta.3
• The server renderer still renders data-reactid somewhat unnecessarily. (Server-rendered HTML polluted with empty data-reactid attributes #10306)
  • Fixed in 16.0.0-beta.3
• Shallow renderer doesn’t pass context to componentWillReceiveProps (to be fixed by Shallow renderer passes context to componentWillReceiveProps #10342)
  • Fixed in 16.0.0-beta.3
• There is an issue with 'use strict' in older browsers (React 16 RC #10294 (comment))
  • Fixed in 16.0.0-beta.3
• In some cases Error: null is reported instead of the real error. ("Error: null" in the captured error warning due to cross-origin issues #10321)
  • Fixed in 16.0.0-beta.3
• There is a report that Google crawler can’t render the page using 16 (link).
  • Fixed in 16.0.0-beta.3
• Some popular third party libraries won’t work yet (e.g. Enzyme).
• (Please report more issues in this thread.)

Updates

• Released 16.0.0-beta.1 on July 24, 2017

• Released 16.0.0-beta.2 on July 27, 2017

  • Fix a crash in server rendering.

• Released 16.0.0-beta.3 on August 3, 2017

  • Fix strict-mode function scope problem (Wrap contents of if-DEV condition in an IIFE #10361)
  • Better error log messaging and cross-origin handling (Cross-origin error handling in DEV #10353, Log captured errors sooner #10373)
  • Shallow renderer improvements (Don't call componentDidUpdate() in shallow renderer #10372, Shallow renderer passes context to componentWillReceiveProps #10342)
  • Edge-case context bugfix (Context improvements #10334)
  • Single point of entry for server rendering (Use single entry point for SSR via browser field #10362)
  • etc.

• Released 16.0.0-beta.4 on August 8, 2017

  • Warn about unresolved function as a child. Warn about unresolved function as a child #10376
  • Remove data-reactid and data-react-checksum from whitelist. Remove data-reactid and data-react-checksum from whitelist #10402
  • New test renderer API features (disabled via feature flag, for now). Add traversal for Fiber test renderer #10377
  • And some other minor updates to slightly reduce bundle size.

• Release 16.0.0-beta.5 on 2017-08-08

  • Fix bugs related to unmounting error boundaries Fix bugs related to unmounting error boundaries #10403
  • Enable new fiber ReactTestRenderer API methods; (previously disabled behind a feature flag) Enable new fiber ReactTestRenderer API methods #10410

• Released 16.0.0-rc.1 on September 6, 2017

  • Fix error: undefined is not a function (evaluating 'owner.getName()') (@fxfactorial in Fixes #10443 #10448 and @bvaughn in RN findNodeHandle no longer adds props directly to read-only owner #10520)
  • Improve error message when ReactDOM loads without React (@aweary in Add explicit invariant when ReactDOM is loaded without React #10449)
  • Warn when nesting 15 subtree inside 16 (@sophiebits in Warn when nesting 15 subtree inside 16 #10434)
  • Don't warn about casing in SSR for non-HTML NS (@sophiebits in Don't warn about casing in SSR for non-HTML NS #10452)
  • Throw error to warn of mistaken loading of prod + dev React bundles (@flarnie in Throw error to warn of mistaken loading of prod + dev React bundles #10446)
  • Reset instance vars before calling commit phase lifecycles (@acdlite in Reset instance vars before calling commit phase lifecycles #10481)
  • Warn if event listener is not a function (@aweary in Warn early for non-functional event listeners #10453)
  • Fix bug where 1k+ react roots would cause error (@acdlite in Track nested updates per root #10574)
  • Allow passing some "unknown" attributes through to DOM components (@nhunzaker in Custom Attributes Scenario 2: Write badly cased attributes. Remove most of whitelist. #10385 , Changes to attribute whitelist logic #10564 , Add missing single-word attributes to property warning list #10495 and others)
  • Fix bug where <select> elements defaulted to first option, even when it was 'disabled'. (@aweary in Default to first non-disabled option for select elements #10456 and @nhunzaker in Add test fixtures to cover disabled selected options #10142)

• Released 16.0.0-rc.2 on September 6, 2017

  • Fix bug where React npm packages would throw an exception on startup in browsers not supporting const natively (@sophiebits in Remove "const" in uncompiled code #10631)

• Released 16.0.0-rc.3 on September 14, 2017

  • Report bad dead code elimination to React DevTools (@gaearon in Report bad dead code elimination to React DevTools #10702)
  • Fix false positive warning when hydrating SVG after SSR (@gaearon in Fix false positive hydration warning for SVG attributes #10676)
  • Add a warning about non-lowercase custom attributes (@gaearon in Warn against custom non-lowercase attributes #10699)
  • Fix a memory leak (@gaearon in Fix context memory leak #10680)
  • Remove deprecated entry point for the shallow renderer (@gaearon in Stop exposing shallow renderer from TestUtils #10682)
  • Remove undocumented TestUtils methods (@gaearon in Remove undocumented TestUtils methods #10681)
  • Add ReactDOM.createPortal() as an “official” API without the unstable prefix (@gaearon in Make ReactDOM.createPortal() official #10675)
  • Don’t repeat Object.assign polyfill twice (@gaearon in Share Object.assign polyfill between UMD builds #10671)