React

React v15.0.1

2016-04-08T00:00:00-07:00

Yesterday afternoon we shipped v15.0.0 and quickly got some feedback about a couple of issues. We apologize for these problems and we've been working since then to make sure we get fixes into your hands as quickly as possible.

The first of these issues is related to the removal of an undocumented API. This API was added to enable JSX Spread Attributes in our JS compile tools (react-tools, JSXTransformer) before Object.assign was standard. When we stopped supporting these tools last year, we kept the API there to catch the longer tail of people using those tools. Meanwhile we moved to using Babel and encouraged others to do the same. Babel will typically compile the spread use to an _extends helper, which will use Object.assign. We did not properly research other compilation tools before deciding to remove the API in v15. Specifically, TypeScript and coffee-react are two popular packages using React.__spread, as well as reactify which still makes use react-tools. In order to make sure that code compiled with these tools is not broken, we will be restoring the React.__spread API and adding a warning. It will be removed in the future so if you maintain a project making using of it, we encourage you to compile to Object.assign directly or a similar helper function.

The second issue resulted in cursor position being lost in controlled inputs. We merged a pull request earlier this week to fix a separate regression from v0.14. Our goal was to target <option> elements but we ended up targeting all interactions with value properties. Unfortunately we didn't test it as thoroughly as we thought. We backed out the offending change and fixed the issue in different way which doesn't have the same problem.

We apologize if you installed 15.0.0 and have encountered these issues yourselves.

As usual, you can get install the react package via npm or download a browser bundle.

React
Dev build with warnings: https://fb.me/react-15.0.1.js
Minified build for production: https://fb.me/react-15.0.1.min.js
React with Add-Ons
Dev build with warnings: https://fb.me/react-with-addons-15.0.1.js
Minified build for production: https://fb.me/react-with-addons-15.0.1.min.js
React DOM (include React in the page before React DOM)
Dev build with warnings: https://fb.me/react-dom-15.0.1.js
Minified build for production: https://fb.me/react-dom-15.0.1.min.js

Changelog #

React #

Restore React.__spread API to unbreak code compiled with some tools making use of this undocumented API. It is now officially deprecated.
@zpao in #6444

ReactDOM #

Fixed issue resulting in loss of cursor position in controlled inputs.
@spicyj in #6449

React v15.0

2016-04-07T00:00:00-07:00

We would like to thank the React community for reporting issues and regressions in the release candidates on our issue tracker. Over the last few weeks we fixed those issues, and now, after two release candidates, we are excited to finally release the stable version of React 15.

As a reminder, we’re switching to major versions to indicate that we have been using React in production for a long time. This 15.0 release follows our previous 0.14 version and we’ll continue to follow semver like we’ve been doing since 2013. It’s also worth noting that we no longer actively support Internet Explorer 8. We believe React will work in its current form there but we will not be prioritizing any efforts to fix new issues that only affect IE8.

React 15 brings significant improvements to how we interact with the DOM:

We are now using document.createElement instead of setting innerHTML when mounting components. This allows us to get rid of the data-reactid attribute on every node and make the DOM lighter. Using document.createElement is also faster in modern browsers and fixes a number of edge cases related to SVG elements and running multiple copies of React on the same page.
Historically our support for SVG has been incomplete, and many tags and attributes were missing. We heard you, and in React 15 we added support for all the SVG attributes that are recognized by today’s browsers. If we missed any of the attributes you’d like to use, please let us know. As a bonus, thanks to using document.createElement, we no longer need to maintain a list of SVG tags, so any SVG tags that were previously unsupported should work just fine in React 15.
We received some amazing contributions from the community in this release, and we would like to highlight this pull request by Michael Wiencek in particular. Thanks to Michael’s work, React 15 no longer emits extra <span> nodes around the text, making the DOM output much cleaner. This was a longstanding annoyance for React users so it’s exciting to accept this as an outside contribution.

While this isn’t directly related to the release, we understand that in order to receive more community contributions like Michael’s, we need to communicate our goals and priorities more openly, and review pull requests more decisively. As a first step towards this, we started publishing React core team weekly meeting notes again. We also intend to introduce an RFC process inspired by Ember RFCs so external contributors can have more insight and influence in the future development of React. We will keep you updated about this on our blog.

We are also experimenting with a new changelog format in this post. Every change now links to the corresponding pull request and mentions the author. Let us know whether you find this useful!

Upgrade Guide #

As usual with major releases, React 15 will remove support for some of the patterns deprecated nine months ago in React 0.14. We know changes can be painful (the Facebook codebase has over 20,000 React components, and that’s not even counting React Native), so we always try to make changes gradually in order to minimize the pain.

If your code is free of warnings when running under React 0.14, upgrading should be easy. The bulk of changes in this release are actually behind the scenes, impacting the way that React interacts with the DOM. The other substantial change is that React now supports the full range of SVG elements and attributes. Beyond that we have a large number of incremental improvements and additional warnings aimed to aid developers. We’ve also laid some groundwork in the core to bring you some new capabilities in future releases.

See the changelog below for more details.

Installation #

We recommend using React from npm and using a tool like browserify or webpack to build your code into a single bundle. To install the two packages:

npm install --save react react-dom

Remember that by default, React runs extra checks and provides helpful warnings in development mode. When deploying your app, set the NODE_ENV environment variable to production to use the production build of React which does not include the development warnings and runs significantly faster.

If you can’t use npm yet, we provide pre-built browser builds for your convenience, which are also available in the react package on bower.

React
Dev build with warnings: https://fb.me/react-15.0.0.js
Minified build for production: https://fb.me/react-15.0.0.min.js
React with Add-Ons
Dev build with warnings: https://fb.me/react-with-addons-15.0.0.js
Minified build for production: https://fb.me/react-with-addons-15.0.0.min.js
React DOM (include React in the page before React DOM)
Dev build with warnings: https://fb.me/react-dom-15.0.0.js
Minified build for production: https://fb.me/react-dom-15.0.0.min.js

Changelog #

Major changes #

document.createElement is in and data-reactid is out #

There were a number of large changes to our interactions with the DOM. One of the most noticeable changes is that we no longer set the data-reactid attribute for each DOM node. While this will make it more difficult to know if a website is using React, the advantage is that the DOM is much more lightweight. This change was made possible by us switching to use document.createElement on initial render. Previously we would generate a large string of HTML and then set node.innerHTML. At the time, this was decided to be faster than using document.createElement for the majority of cases and browsers that we supported. Browsers have continued to improve and so overwhelmingly this is no longer true. By using createElement we can make other parts of React faster. The ids were used to map back from events to the original React component, meaning we had to do a bunch of work on every event, even though we cached this data heavily. As we’ve all experienced, caching and in particularly invalidating caches, can be error prone and we saw many hard to reproduce issues over the years as a result. Now we can build up a direct mapping at render time since we already have a handle on the node.

Note: data-reactid is still present for server-rendered content, however it is much smaller than before and is simply an auto-incrementing counter.

@spicyj in #5205
No more extra <span>s #

Another big change with our DOM interaction is how we render text blocks. Previously you may have noticed that React rendered a lot of extra <span>s. For example, in our most basic example on the home page we render <div>Hello {this.props.name}</div>, resulting in markup that contained 2 <span>s. Now we’ll render plain text nodes interspersed with comment nodes that are used for demarcation. This gives us the same ability to update individual pieces of text, without creating extra nested nodes. Very few people have depended on the actual markup generated here so it’s likely you are not impacted. However if you were targeting these <span>s in your CSS, you will need to adjust accordingly. You can always render them explicitly in your components.

@mwiencek in #5753
Rendering null now uses comment nodes #

We’ve also made use of these comment nodes to change what null renders to. Rendering to null was a feature we added in React 0.11 and was implemented by rendering <noscript> elements. By rendering to comment nodes now, there’s a chance some of your CSS will be targeting the wrong thing, specifically if you are making use of :nth-child selectors. React’s use of the <noscript> tag has always been considered an implementation detail of how React targets the DOM. We believe they are safe changes to make without going through a release with warnings detailing the subtle differences as they are details that should not be depended upon. Additionally, we have seen that these changes have improved React performance for many typical applications.

@spicyj in #5451
Functional components can now return null too #

We added support for defining stateless components as functions in React 0.14. However, React 0.14 still allowed you to define a class component without extending React.Component or using React.createClass(), so we couldn’t reliably tell if your component is a function or a class, and did not allow returning null from it. This issue is solved in React 15, and you can now return null from any component, whether it is a class or a function.

@jimfb in #5884
Improved SVG support #

All SVG tags are now fully supported. (Uncommon SVG tags are not present on the React.DOM element helper, but JSX and React.createElement work on all tag names.) All SVG attributes that are implemented by the browsers should be supported too. If you find any attributes that we have missed, please let us know in this issue.

@zpao in #6243

Breaking changes #

No more extra <span>s #

It’s worth calling out the DOM structure changes above again, in particular the change from <span>s. In the course of updating the Facebook codebase, we found a very small amount of code that was depending on the markup that React generated. Some of these cases were integration tests like WebDriver which were doing very specific XPath queries to target nodes. Others were simply tests using ReactDOM.renderToStaticMarkup and comparing markup. Again, there were a very small number of changes that had to be made, but we don’t want anybody to be blindsided. We encourage everybody to run their test suites when upgrading and consider alternative approaches when possible. One approach that will work for some cases is to explicitly use <span>s in your render method.

@mwiencek in #5753
React.cloneElement() now resolves defaultProps #

We fixed a bug in React.cloneElement() that some components may rely on. If some of the props received by cloneElement() are undefined, it used to return an element with undefined values for those props. In React 15, we’re changing it to be consistent with createElement(). Now any undefined props passed to cloneElement() are resolved to the corresponding component’s defaultProps. Only one of our 20,000 React components was negatively affected by this so we feel comfortable releasing this change without keeping the old behavior for another release cycle.

@truongduy134 in #5997
ReactPerf.getLastMeasurements() is opaque #

This change won’t affect applications but may break some third-party tools. We are revamping ReactPerf implementation and plan to release it during the 15.x cycle. The internal performance measurement format is subject to change so, for the time being, we consider the return value of ReactPerf.getLastMeasurements() an opaque data structure that should not be relied upon.

@gaearon in #6286
Removed deprecations #

These deprecations were introduced nine months ago in v0.14 with a warning and are removed:
- Deprecated APIs are removed from the React top-level export: findDOMNode, render, renderToString, renderToStaticMarkup, and unmountComponentAtNode. As a reminder, they are now available on ReactDOM and ReactDOMServer.
  @jimfb in #5832
- Deprecated addons are removed: batchedUpdates and cloneWithProps.
  @jimfb in #5859, @zpao in #6016
- Deprecated component instance methods are removed: setProps, replaceProps, and getDOMNode.
  @jimfb in #5570
- Deprecated CommonJS react/addons entry point is removed. As a reminder, you should use separate react-addons-* packages instead. This only applies if you use the CommonJS builds.
  @gaearon in #6285
- Passing children to void elements like <input> was deprecated, and now throws an error.
  @jonhester in #3372
- React-specific properties on DOM refs (e.g. this.refs.div.props) were deprecated, and are removed now.
  @jimfb in #5495

New deprecations, introduced with a warning #

Each of these changes will continue to work as before with a new warning until the release of React 16 so you can upgrade your code gradually.

LinkedStateMixin and valueLink are now deprecated due to very low popularity. If you need this, you can use a wrapper component that implements the same behavior: react-linked-input.
@jimfb in #6127
Future versions of React will treat <input value={null}> as a request to clear the input. However, React 0.14 has been ignoring value={null}. React 15 warns you on a null input value and offers you to clarify your intention. To fix the warning, you may explicitly pass an empty string to clear a controlled input, or pass undefined to make the input uncontrolled.
@antoaravinth in #5048
ReactPerf.printDOM() was renamed to ReactPerf.printOperations(), and ReactPerf.getMeasurementsSummaryMap() was renamed to ReactPerf.getWasted().
@gaearon in #6287

New helpful warnings #

If you use a minified copy of the development build, React DOM kindly encourages you to use the faster production build instead.
@spicyj in #5083
React DOM: When specifying a unit-less CSS value as a string, a future version will not add px automatically. This version now warns in this case (ex: writing style={{width: '300'}}. Unitless number values like width: 300 are unchanged.
@pluma in #5140
Synthetic Events will now warn when setting and accessing properties (which will not get cleared appropriately), as well as warn on access after an event has been returned to the pool.
@kentcdodds in #5940 and @koba04 in #5947
Elements will now warn when attempting to read ref and key from the props.
@prometheansacrifice in #5744
React will now warn if you pass a different props object to super() in the constructor.
@prometheansacrifice in #5346
React will now warn if you call setState() inside getChildContext().
@raineroviir in #6121
React DOM now attempts to warn for mistyped event handlers on DOM elements, such as onclick which should be onClick.
@ali in #5361
React DOM now warns about NaN values in style.
@jontewks in #5811
React DOM now warns if you specify both value and defaultValue for an input.
@mgmcdermott in #5823
React DOM now warns if an input switches between being controlled and uncontrolled.
@TheBlasfem in #5864
React DOM now warns if you specify onFocusIn or onFocusOut handlers as they are unnecessary in React.
@jontewks in #6296
React now prints a descriptive error message when you pass an invalid callback as the last argument to ReactDOM.render(), this.setState(), or this.forceUpdate().
@conorhastings in #5193 and @gaearon in #6310
Add-Ons: TestUtils.Simulate() now prints a helpful message if you attempt to use it with shallow rendering.
@conorhastings in #5358
PropTypes: arrayOf() and objectOf() provide better error messages for invalid arguments.
@chicoxyzzy in #5390

Notable bug fixes #

Fixed multiple small memory leaks.
@spicyj in #4983 and @victor-homyakov in #6309
Input events are handled more reliably in IE 10 and IE 11; spurious events no longer fire when using a placeholder.
@jquense in #4051
The componentWillReceiveProps() lifecycle method is now consistently called when context changes.
@milesj in #5787
React.cloneElement() doesn’t append slash to an existing key when used inside React.Children.map().
@ianobermiller in #5892
React DOM now supports the cite and profile HTML attributes.
@AprilArcus in #6094 and @saiichihashimoto in #6032
React DOM now supports cssFloat, gridRow and gridColumn CSS properties.
@stevenvachon in #6133 and @mnordick in #4779
React DOM now correctly handles borderImageOutset, borderImageWidth, borderImageSlice, floodOpacity, strokeDasharray, and strokeMiterlimit as unitless CSS properties.
@rofrischmann in #6210 and #6270
React DOM now supports the onAnimationStart, onAnimationEnd, onAnimationIteration, onTransitionEnd, and onInvalid events. Support for onLoad has been added to object elements.
@tomduncalf in #5187, @milesj in #6005, and @ara4n in #5781
React DOM now defaults to using DOM attributes instead of properties, which fixes a few edge case bugs. Additionally the nullification of values (ex: href={null}) now results in the forceful removal, no longer trying to set to the default value used by browsers in the absence of a value.
@syranide in #1510
React DOM does not mistakingly coerce children to strings for Web Components.
@jimfb in #5093
React DOM now correctly normalizes SVG <use> events.
@edmellum in #5720
React DOM does not throw if a <select> is unmounted while its onChange handler is executing.
@sambev in #6028
React DOM does not throw in Windows 8 apps.
@Andrew8xx8 in #6063
React DOM does not throw when asynchronously unmounting a child with a ref.
@yiminghe in #6095
React DOM no longer forces synchronous layout because of scroll position tracking.
@syranide in #2271
Object.is is used in a number of places to compare values, which leads to fewer false positives, especially involving NaN. In particular, this affects the shallowCompare add-on.
@chicoxyzzy in #6132
Add-Ons: ReactPerf no longer instruments adding or removing an event listener because they don’t really touch the DOM due to event delegation.
@antoaravinth in #5209

Other improvements #

React now uses loose-envify instead of envify so it installs fewer transitive dependencies.
@qerub in #6303
Shallow renderer now exposes getMountedInstance().
@glenjamin in #4918
Shallow renderer now returns the rendered output from render().
@simonewebdesign in #5411
React no longer depends on ES5 shams for Object.create and Object.freeze in older environments. It still, however, requires ES5 shims in those environments.
@dgreensp in #4959
React DOM now allows data- attributes with names that start with numbers.
@nLight in #5216
React DOM adds a new suppressContentEditableWarning prop for components like Draft.js that intentionally manage contentEditable children with React.
@mxstbr in #6112
React improves the performance for createClass() on complex specs.
@spicyj in #5550

React v0.14.8

2016-03-29T00:00:00-07:00

We have already released two release candidates for React 15, and the final version is coming soon.

However Ian Christian Myers discovered a memory leak related to server rendering in React 0.14 and contributed a fix. While this memory leak has already been fixed in a different way in the React 15 release candidates, we decided to cut another 0.14 release that contains just this fix.

The release is now available for download:

React
Dev build with warnings: https://fb.me/react-0.14.8.js
Minified build for production: https://fb.me/react-0.14.8.min.js
React with Add-Ons
Dev build with warnings: https://fb.me/react-with-addons-0.14.8.js
Minified build for production: https://fb.me/react-with-addons-0.14.8.min.js
React DOM (include React in the page before React DOM)
Dev build with warnings: https://fb.me/react-dom-0.14.8.js
Minified build for production: https://fb.me/react-dom-0.14.8.min.js
React DOM Server (include React in the page before React DOM Server)
Dev build with warnings: https://fb.me/react-dom-server-0.14.8.js
Minified build for production: https://fb.me/react-dom-server-0.14.8.min.js

We've also published version 0.14.8 of the react, react-dom, and addons packages on npm and the react package on bower.

Changelog #

React #

Fixed memory leak when rendering on the server

React v15.0 Release Candidate 2

2016-03-16T00:00:00-07:00

Today we're releasing a second release candidate for version 15. Primarily this is to address 2 issues, but we also picked up a few small changes from new contributors, including some improvements to some of our new warnings.

The most pressing change that was made is to fix a bug in our new code that removes <span>s, as discussed in the original RC1 post. Specifically we have some code that takes a different path in IE11 and Edge due to the speed of some DOM operations. There was a bug in this code which didn't break out of the optimization for DocumentFragments, resulting in text not appearing at all. Thanks to the several people who reported this.

The other change is to our SVG code. In RC1 we had made the decision to pass through all attributes directly. This led to some confusion with class vs className and ultimately led us to reconsider our position on the approach. Passing through all attributes meant that we would have two different patterns for using React where things like hyphenated attributes would work for SVG but not HTML. In the future, we might change our approach to the problem for HTML as well but in the meantime, maintaining consistency is important. So we reverted the changes that allowed the attributes to be passed through and instead expanded the SVG property list to include all attributes that are in the spec. We believe we have everything now but definitely let us know if we missed anything. It was and still is our intent to support the full range of SVG tags and attributes in this release.

Thanks again to everybody who has tried the RC1 and reported issues. It has been extremely important and we wouldn't be able to do this without your help!

Installation #

We recommend using React from npm and using a tool like browserify or webpack to build your code into a single bundle. To install the two packages:

npm install --save react@15.0.0-rc.2 react-dom@15.0.0-rc.2

If you can’t use npm yet, we provide pre-built browser builds for your convenience, which are also available in the react package on bower.

React
Dev build with warnings: https://fb.me/react-15.0.0-rc.2.js
Minified build for production: https://fb.me/react-15.0.0-rc.2.min.js
React with Add-Ons
Dev build with warnings: https://fb.me/react-with-addons-15.0.0-rc.2.js
Minified build for production: https://fb.me/react-with-addons-15.0.0-rc.2.min.js
React DOM (include React in the page before React DOM)
Dev build with warnings: https://fb.me/react-dom-15.0.0-rc.2.js
Minified build for production: https://fb.me/react-dom-15.0.0-rc.2.min.js

React v15.0 Release Candidate

2016-03-07T00:00:00-08:00

Sorry for the small delay in releasing this. As we said, we've been busy binge-watching House of Cards. That scene in the last episode where Francis and Claire Underwood ████████████████████████████████████. WOW!

But now we're ready, so without further ado, we're shipping a release candidate for React v15 now. As a reminder, we're switching to major versions to indicate that we have been using React in production for a long time. This 15.0 release follows our previous 0.14 version and we'll continue to follow semver like we've been doing since 2013. It's also worth noting that we no longer actively support Internet Explorer 8. We believe React will work in its current form there but we will not be prioritizing any efforts to fix new issues that only affect IE8.

Please try it out before we publish the final release. Let us know if you run into any problems by filing issues on our GitHub repo.

Upgrade Guide #

Like always, we have a few breaking changes in this release. We know changes can be painful (the Facebook codebase has over 15,000 React components), so we always try to make changes gradually in order to minimize the pain.

If your code is free of warnings when running under React 0.14, upgrading should be easy. The bulk of changes in this release are actually behind the scenes, impacting the way that React interacts with the DOM. The other substantial change is that React now supports the full range of SVG elements and attributes. Beyond that we have a large number of incremental improvements and additional warnings aimed to aid developers. We've also laid some groundwork in the core to bring you some new capabilities in future releases.

See the changelog below for more details.

Installation #

We recommend using React from npm and using a tool like browserify or webpack to build your code into a single bundle. To install the two packages:

npm install --save react@15.0.0-rc.1 react-dom@15.0.0-rc.1

If you can’t use npm yet, we provide pre-built browser builds for your convenience, which are also available in the react package on bower.

React
Dev build with warnings: https://fb.me/react-15.0.0-rc.1.js
Minified build for production: https://fb.me/react-15.0.0-rc.1.min.js
React with Add-Ons
Dev build with warnings: https://fb.me/react-with-addons-15.0.0-rc.1.js
Minified build for production: https://fb.me/react-with-addons-15.0.0-rc.1.min.js
React DOM (include React in the page before React DOM)
Dev build with warnings: https://fb.me/react-dom-15.0.0-rc.1.js
Minified build for production: https://fb.me/react-dom-15.0.0-rc.1.min.js

Changelog #

Major changes #

document.createElement is in and data-reactid is out #

There were a number of large changes to our interactions with the DOM. One of the most noticeable changes is that we no longer set the data-reactid attribute for each DOM node. While this will make it much more difficult to know if a website is using React, the advantage is that the DOM is much more lightweight. This change was made possible by us switching to use document.createElement on initial render. Previously we would generate a large string of HTML and then set node.innerHTML. At the time, this was decided to be faster than using document.createElement for the majority of cases and browsers that we supported. Browsers have continued to improve and so overwhelmingly this is no longer true. By using createElement we can make other parts of React faster. The ids were used to map back from events to the original React component, meaning we had to do a bunch of work on every event, even though we cached this data heavily. As we've all experienced, caching and in particularly invalidating caches, can be error prone and we saw many hard to reproduce issues over the years as a result. Now we can build up a direct mapping at render time since we already have a handle on the node.
No more extra <span>s #

Another big change with our DOM interaction is how we render text blocks. Previously you may have noticed that React rendered a lot of extra <span>s. Eg, in our most basic example on the home page we render <div>Hello {this.props.name}</div>, resulting in markup that contained 2 <span>s. Now we'll render plain text nodes interspersed with comment nodes that are used for demarcation. This gives us the same ability to update individual pieces of text, without creating extra nested nodes. Very few people have depended on the actual markup generated here so it's likely you are not impacted. However if you were targeting these <span>s in your CSS, you will need to adjust accordingly. You can always render them explicitly in your components.
Rendering null now uses comment nodes #

We've also made use of these comment nodes to change what null renders to. Rendering to null was a feature we added in React v0.11 and was implemented by rendering <noscript> elements. By rendering to comment nodes now, there's a chance some of your CSS will be targeting the wrong thing, specifically if you are making use of :nth-child selectors. This, along with the other changes mentioned above, have always been considered implementation details of how React targets the DOM. We believe they are safe changes to make without going through a release with warnings detailing the subtle differences as they are details that should not be depended upon. Additionally, we have seen that these changes have improved React performance for many typical applications.
Improved SVG support #

All SVG tags and attributes are now fully supported. (Uncommon SVG tags are not present on the React.DOM element helper, but JSX and React.createElement work on all tag names.) All SVG attributes match their original capitalization and hyphenation as defined in the specification (ex: gradientTransform must be camel-cased but clip-path should be hyphenated).

Breaking changes #

It's worth calling out the DOM structure changes above again, in particular the change from <span>s. In the course of updating the Facebook codebase, we found a very small amount of code that was depending on the markup that React generated. Some of these cases were integration tests like WebDriver which were doing very specific XPath queries to target nodes. Others were simply tests using ReactDOM.renderToStaticMarkup and comparing markup. Again, there were a very small number of changes that had to be made, but we don't want anybody to be blindsided. We encourage everybody to run their test suites when upgrading and consider alternative approaches when possible. One approach that will work for some cases is to explicitly use <span>s in your render method.

These deprecations were introduced in v0.14 with a warning and the APIs are now removed.

Deprecated APIs removed from React, specifically findDOMNode, render, renderToString, renderToStaticMarkup, and unmountComponentAtNode.
Deprecated APIs removed from React.addons, specifically batchedUpdates and cloneWithProps.
Deprecated APIs removed from component instances, specifically setProps, replaceProps, and getDOMNode.

New deprecations, introduced with a warning #

Each of these changes will continue to work as before with a new warning until the release of React 16 so you can upgrade your code gradually.

LinkedStateMixin and valueLink are now deprecated due to very low popularity. If you need this, you can use a wrapper component that implements the same behavior: react-linked-input.

New helpful warnings #

If you use a minified copy of the development build, React DOM kindly encourages you to use the faster production build instead.
React DOM: When specifying a unit-less CSS value as a string, a future version will not add px automatically. This version now warns in this case (ex: writing style={{width: '300'}}. (Unitless number values like width: 300 are unchanged.)
Synthetic Events will now warn when setting and accessing properties (which will not get cleared appropriately), as well as warn on access after an event has been returned to the pool.
Elements will now warn when attempting to read ref and key from the props.
React DOM now attempts to warn for mistyped event handlers on DOM elements (ex: onclick which should be onClick)

Notable bug fixes #

Fixed multiple small memory leaks
Input events are handled more reliably in IE 10 and IE 11; spurious events no longer fire when using a placeholder.
React DOM now supports the cite and profile HTML attributes.
React DOM now supports the onAnimationStart, onAnimationEnd, onAnimationIteration, onTransitionEnd, and onInvalid events. Support for onLoad has been added to object elements.
Object.is is used in a number of places to compare values, which leads to fewer false positives, especially involving NaN. In particular, this affects the shallowCompare add-on.
React DOM now defaults to using DOM attributes instead of properties, which fixes a few edge case bugs. Additionally the nullification of values (ex: href={null}) now results in the forceful removal, no longer trying to set to the default value used by browsers in the absence of a value.

New Versioning Scheme

2016-02-19T00:00:00-08:00

Today we're announcing that we're switching to major revisions for React. The current version is 0.14.7. The next release will be: 15.0.0

This change shouldn't materially affect most of you. Moving to major semver versions simply helps indicate our commitment to stability and gives us the flexibility to add new backwards-compatible features in minor releases. This means we can have fewer major releases and you won't have to wait as long to take advantage of improvements to React. Plus, if you're a component author, this versioning scheme gives you the flexibility to support two major versions of React at the same time so you don't need to leave anyone behind.

The core of the React API has been stable for years. Our business as well as many of yours all depend heavily on the use of React as a core piece of our infrastructure. We're committed to the stability as well as the progress of React going forward.

Bring Everyone Along #

React isn't just a library but an ecosystem. We know that your applications and ours are not just isolated islands of code. It is a network of your own application code, your own open source components and third party libraries that all depend on React.

Therefore it is important that we don't just upgrade our own codebases but that we bring our whole community with us. We take the upgrade path very seriously - for everyone.

Introducing Minor Releases #

Ideally everyone could just depend on the latest version of React all the time.

We know that in practice that is not possible. In the future, we expect more new additive APIs rather than breakage of existing ones. By moving to major revisions in the semver scheme, we can release new versions without breaking existing ones.

That means that if one component needs a new API, there is no need for any of the other components to do any further work. They remain compatible.

What Happened to 1.0.0? #

Part of React's growth and popularity is that it is stable and performant in production. People have long asked what React v1.0 will look. Technically some breaking changes are important to avoid stagnating, but we still achieve stability by making it easy to upgrade. If major version numbers indicate API stability and engender trust that it can be used in production, then we got there a long time ago. There are too many preconceived notions of what v1.0 is. We're still following semver. We're just communicating stability by moving the 0 from the beginning to the end.

Breaking Changes #

Minor revision releases will include deprecation warnings and tips for how to upgrade an API or pattern that will be removed or changed in the future.

We will continue to release codemods for common patterns to make automatic upgrades of your codebase easier.

Once we've reached the end of life for a particular major version, we'll release a new major version where all deprecated APIs have been removed.

Avoiding The Major Cliff #

If you try to upgrade your component to 16.0.0 you might find that your application no longer works if you still have other dependencies. E.g. if Ryan's and Jed's components are only compatible with 15.x.x.

Worst case, you revert back to 15.1.0 for your application. Since you'll want to use your component, you might also revert that one.

Of course, Ryan and Jed think the same way. If we're not careful, we can hit a cliff where nobody upgrades. This has happened to many software project ecosystems in the past.

Therefore, we're committed to making it easy for most components and libraries built on top of React to be compatible with two major versions at the same time. We will do this by introducing new APIs before completely removing the old ones, thereby avoiding those cliffs.

Discontinuing IE 8 Support in React DOM

2016-01-12T00:00:00-08:00

Since its 2013 release, React has supported all popular browsers, including Internet Explorer 8 and above. We handle normalizing many quirks present in old browser versions, including event system differences, so that your app code doesn't have to worry about most browser bugs.

Today, Microsoft discontinued support for older versions of IE. Starting with React v15, we're discontinuing React DOM's support for IE 8. We've heard that most React DOM apps already don't support old versions of Internet Explorer, so this shouldn't affect many people. This change will help us develop faster and make React DOM even better. (We won't actively remove IE 8–related code quite yet, but we will deprioritize new bugs that are reported. If you need to support IE 8 we recommend you stay on React v0.14.)

React DOM will continue to support IE 9 and above for the foreseeable future.

(A => B) !=> (B => A)

2016-01-08T00:00:00-08:00

The documentation for componentWillReceiveProps states that componentWillReceiveProps will be invoked when the props change as the result of a rerender. Some people assume this means "if componentWillReceiveProps is called, then the props must have changed", but that conclusion is logically incorrect.

The guiding principle is one of my favorites from formal logic/mathematics:

A implies B does not imply B implies A

Example: "If I eat moldy food, then I will get sick" does not imply "if I am sick, then I must have eaten moldy food". There are many other reasons I could be feeling sick. For instance, maybe the flu is circulating around the office. Similarly, there are many reasons that componentWillReceiveProps might get called, even if the props didn’t change.

If you don’t believe me, call ReactDOM.render() three times with the exact same props, and try to predict the number of times componentWillReceiveProps will get called:

class Component extends React.Component {
  componentWillReceiveProps(nextProps) {
    console.log('componentWillReceiveProps', nextProps.data.bar);
  }
  render() {
    return <div>Bar {this.props.data.bar}!</div>;
  }
}

var container = document.getElementById('container');

var mydata = {bar: 'drinks'};
ReactDOM.render(<Component data={mydata} />, container);
ReactDOM.render(<Component data={mydata} />, container);
ReactDOM.render(<Component data={mydata} />, container);

In this case, the answer is "2". React calls componentWillReceiveProps twice (once for each of the two updates). Both times, the value of "drinks" is printed (ie. the props didn’t change).

To understand why, we need to think about what could have happened. The data could have changed between the initial render and the two subsequent updates, if the code had performed a mutation like this:

var mydata = {bar: 'drinks'};
ReactDOM.render(<Component data={mydata} />, container);
mydata.bar = 'food'
ReactDOM.render(<Component data={mydata} />, container);
mydata.bar = 'noise'
ReactDOM.render(<Component data={mydata} />, container);

React has no way of knowing that the data didn’t change. Therefore, React needs to call componentWillReceiveProps, because the component needs to be notified of the new props (even if the new props happen to be the same as the old props).

You might think that React could just use smarter checks for equality, but there are some issues with this idea:

The old mydata and the new mydata are actually the same physical object (only the object’s internal value changed). Since the references are triple-equals-equal, doing an equality check doesn’t tell us if the value has changed. The only possible solution would be to have created a deep copy of the data, and then later do a deep comparison - but this can be prohibitively expensive for large data structures (especially ones with cycles).
The mydata object might contain references to functions which have captured variables within closures. There is no way for React to peek into these closures, and thus no way for React to copy them and/or verify equality.
The mydata object might contain references to objects which are re-instantiated during the parent's render (ie. not triple-equals-equal) but are conceptually equal (ie. same keys and same values). A deep-compare (expensive) could detect this, except that functions present a problem again because there is no reliable way to compare two functions to see if they are semantically equivalent.

Given the language constraints, it is sometimes impossible for us to achieve meaningful equality semantics. In such cases, React will call componentWillReceiveProps (even though the props might not have changed) so the component has an opportunity to examine the new props and act accordingly.

As a result, your implementation of componentWillReceiveProps MUST NOT assume that your props have changed. If you want an operation (such as a network request) to occur only when props have changed, your componentWillReceiveProps code needs to check to see if the props actually changed.

React v0.14.4

2015-12-29T00:00:00-08:00

Happy December! We have a minor point release today. It has just a few small bug fixes.

The release is now available for download:

React
Dev build with warnings: https://fb.me/react-0.14.4.js
Minified build for production: https://fb.me/react-0.14.4.min.js
React with Add-Ons
Dev build with warnings: https://fb.me/react-with-addons-0.14.4.js
Minified build for production: https://fb.me/react-with-addons-0.14.4.min.js
React DOM (include React in the page before React DOM)
Dev build with warnings: https://fb.me/react-dom-0.14.4.js
Minified build for production: https://fb.me/react-dom-0.14.4.min.js
React DOM Server (include React in the page before React DOM Server)
Dev build with warnings: https://fb.me/react-dom-server-0.14.4.js
Minified build for production: https://fb.me/react-dom-server-0.14.4.min.js

We've also published version 0.14.4 of the react, react-dom, and addons packages on npm and the react package on bower.

Changelog #

React #

Minor internal changes for better compatibility with React Native

React DOM #

The autoCapitalize and autoCorrect props are now set as attributes in the DOM instead of properties to improve cross-browser compatibility
Fixed bug with controlled <select> elements not handling updates properly

React Perf Add-on #

Some DOM operation names have been updated for clarity in the output of .printDOM()

React Components, Elements, and Instances

2015-12-18T00:00:00-08:00

The difference between components, their instances, and elements confuses many React beginners. Why are there three different terms to refer to something that is painted on screen?

Managing the Instances #

If you’re new to React, you probably only worked with component classes and instances before. For example, you may declare a Button component by creating a class. When the app is running, you may have several instances of this component on screen, each with its own properties and local state. This is the traditional object-oriented UI programming. Why introduce elements?

In this traditional UI model, it is up to you to take care of creating and destroying child component instances. If a Form component wants to render a Button component, it needs to create its instance, and manually keep it up to date with any new information.

class Form extends TraditionalObjectOrientedView {
  render() {
    // Read some data passed to the view
    const { isSubmitted, buttonText } = this.attrs;

    if (!isSubmitted && !this.button) {
      // Form is not yet submitted. Create the button!
      this.button = new Button({
        children: buttonText,
        color: 'blue'
      });
      this.el.appendChild(this.button.el);
    }

    if (this.button) {
      // The button is visible. Update its text!
      this.button.attrs.children = buttonText;
      this.button.render();
    }

    if (isSubmitted && this.button) {
      // Form was submitted. Destroy the button!
      this.el.removeChild(this.button.el);
      this.button.destroy();
    }

    if (isSubmitted && !this.message) {
      // Form was submitted. Show the success message!
      this.message = new Message({ text: 'Success!' });
      this.el.appendChild(this.message.el);
    }
  }
}

This is pseudocode, but it is more or less what you end up with when you write composite UI code that behaves consistently in an object-oriented way using a library like Backbone.

Each component instance has to keep references to its DOM node and to the instances of the children components, and create, update, and destroy them when the time is right. The lines of code grow as the square of the number of possible states of the component, and the parents have direct access to their children component instances, making it hard to decouple them in the future.

So how is React different?

Elements Describe the Tree #

In React, this is where the elements come to rescue. An element is a plain object describing a component instance or DOM node and its desired properties. It contains only information about the component type (for example, a Button), its properties (for example, its color), and any child elements inside it.

An element is not an actual instance. Rather, it is a way to tell React what you want to see on the screen. You can’t call any methods on the element. It’s just an immutable description object with two fields: type: (string | ReactClass) and props: Object¹.

DOM Elements #

When an element’s type is a string, it represents a DOM node with that tag name, and props correspond to its attributes. This is what React will render. For example:

{
  type: 'button',
  props: {
    className: 'button button-blue',
    children: {
      type: 'b',
      props: {
        children: 'OK!'
      }
    }
  }
}

This element is just a way to represent the following HTML as a plain object:

<button class='button button-blue'>
  <b>
    OK!
  </b>
</button>

Note how elements can be nested. By convention, when we want to create an element tree, we specify one or more child elements as the children prop of their containing element.

What’s important is that both child and parent elements are just descriptions and not the actual instances. They don’t refer to anything on the screen when you create them. You can create them and throw them away, and it won’t matter much.

React elements are easy to traverse, don’t need to be parsed, and of course they are much lighter than the actual DOM elements—they’re just objects!

Component Elements #

However, the type of an element can also be a function or a class corresponding to a React component:

{
  type: Button,
  props: {
    color: 'blue',
    children: 'OK!'
  }
}

This is the core idea of React.

An element describing a component is also an element, just like an element describing the DOM node. They can be nested and mixed with each other.

This feature lets you define a DangerButton component as a Button with a specific color property value without worrying about whether Button renders to a DOM <button>, a <div>, or something else entirely:

const DangerButton = ({ children }) => ({
  type: Button,
  props: {
    color: 'red',
    children: children
  }
});

You can mix and match DOM and component elements in a single element tree:

const DeleteAccount = () => ({
  type: 'div',
  props: {
    children: [{
      type: 'p',
      props: {
        children: 'Are you sure?'
      }
    }, {
      type: DangerButton,
      props: {
        children: 'Yep'
      }
    }, {
      type: Button,
      props: {
        color: 'blue',
        children: 'Cancel'
      }
   }]
});

Or, if you prefer JSX:

const DeleteAccount = () => (
  <div>
    <p>Are you sure?</p>
    <DangerButton>Yep</DangerButton>
    <Button color='blue'>Cancel</Button>
  </div>
);

This mix and matching helps keep components decoupled from each other, as they can express both is-a and has-a relationships exclusively through composition:

Button is a DOM <button> with specific properties.
DangerButton is a Button with specific properties.
DeleteAccount contains a Button and a DangerButton inside a <div>.

Components Encapsulate Element Trees #

When React sees an element with a function or class type, it knows to ask that component what element it renders to, given the corresponding props.

When it sees this element:

{
  type: Button,
  props: {
    color: 'blue',
    children: 'OK!'
  }
}

React will ask Button what it renders to. The Button will return this element:

{
  type: 'button',
  props: {
    className: 'button button-blue',
    children: {
      type: 'b',
      props: {
        children: 'OK!'
      }
    }
  }
}

React will repeat this process until it knows the underlying DOM tag elements for every component on the page.

React is like a child asking “what is Y” for every “X is Y” you explain to them until they figure out every little thing in the world.

Remember the Form example above? It can be written in React as follows¹:

const Form = ({ isSubmitted, buttonText }) => {
  if (isSubmitted) {
    // Form submitted! Return a message element.
    return {
      type: Message,
      props: {
        text: 'Success!'
      }
    };
  }

  // Form is still visible! Return a button element.
  return {
    type: Button,
    props: {
      children: buttonText,
      color: 'blue'
    }
  };
};

That’s it! For a React component, props are the input, and an element tree is the output.

The returned element tree can contain both elements describing DOM nodes, and elements describing other components. This lets you compose independent parts of UI without relying on their internal DOM structure.

We let React create, update, and destroy instances. We describe them with elements we return from the components, and React takes care of managing the instances.

Components Can Be Classes or Functions #

In the code above, Form, Message, and Button are React components. They can either be written as functions, like above, or as classes descending from React.Component. These three ways to declare a component are mostly equivalent:

// 1) As a function of props
const Button = ({ children, color }) => ({
  type: 'button',
  props: {
    className: 'button button-' + color,
    children: {
      type: 'b',
      props: {
        children: children
      }
    }
  }
});

// 2) Using the React.createClass() factory
const Button = React.createClass({
  render() {
    const { children, color } = this.props;
    return {
      type: 'button',
      props: {
        className: 'button button-' + color,
        children: {
          type: 'b',
          props: {
            children: children
          }
        }
      }
    };
  }
});

// 3) As an ES6 class descending from React.Component
class Button extends React.Component {
  render() {
    const { children, color } = this.props;
    return {
      type: 'button',
      props: {
        className: 'button button-' + color,
        children: {
          type: 'b',
          props: {
            children: children
          }
        }
      }
    };
  }
}

When a component is defined as a class, it is a little bit more powerful than a functional component. It can store some local state and perform custom logic when the corresponding DOM node is created or destroyed.

A functional component is less powerful but is simpler, and acts like a class component with just a single render() method. Unless you need features available only in a class, we encourage you to use functional components instead.

However, whether functions or classes, fundamentally they are all components to React. They take the props as their input, and return the elements as their output.

Top-Down Reconciliation #

When you call:

ReactDOM.render({
  type: Form,
  props: {
    isSubmitted: false,
    buttonText: 'OK!'
  }
}, document.getElementById('root'));

React will ask the Form component what element tree it returns, given those props. It will gradually “refine” its understanding of your component tree in terms of simpler primitives:

// React: You told me this...
{
  type: Form,
  props: {
    isSubmitted: false,
    buttonText: 'OK!'
  }
}

// React: ...And Form told me this...
{
  type: Button,
  props: {
    children: 'OK!',
    color: 'blue'
  }
}

// React: ...and Button told me this! I guess I'm done.
{
  type: 'button',
  props: {
    className: 'button button-blue',
    children: {
      type: 'b',
      props: {
        children: 'OK!'
      }
    }
  }
}

This is a part of the process that React calls reconciliation which starts when you call ReactDOM.render() or setState(). By the end of the reconciliation, React knows the result DOM tree, and a renderer like react-dom or react-native applies the minimal set of changes necessary to update the DOM nodes (or the platform-specific views in case of React Native).

This gradual refining process is also the reason React apps are easy to optimize. If some parts of your component tree become too large for React to visit efficiently, you can tell it to skip this “refining” and diffing certain parts of the tree if the relevant props have not changed. It is very fast to calculate whether the props have changed if they are immutable, so React and immutability work great together, and can provide great optimizations with the minimal effort.

You might have noticed that this blog entry talks a lot about components and elements, and not so much about the instances. The truth is, instances have much less importance in React than in most object-oriented UI frameworks.

Only components declared as classes have instances, and you never create them directly: React does that for you. While mechanisms for a parent component instance to access a child component instance exist, they are only used for imperative actions (such as setting focus on a field), and should generally be avoided.

React takes care of creating an instance for every class component, so you can write components in an object-oriented way with methods and local state, but other than that, instances are not very important in the React’s programming model and are managed by React itself.

Summary #

An element is a plain object describing what you want to appear on the screen in terms of the DOM nodes or other components. Elements can contain other elements in their props. Creating a React element is cheap. Once an element is created, it is never mutated.

A component can be declared in several different ways. It can be a class with a render() method. Alternatively, in simple cases, it can be defined as a function. In either case, it takes props as an input, and returns an element tree as the output.

When a component receives some props as an input, it is because a particular parent component returned an element with its type and these props. This is why people say that the props flows one way in React: from parents to children.

An instance is what you refer to as this in the component class you write. It is useful for storing local state and reacting to the lifecycle events.

Functional components don’t have instances at all. Class components have instances, but you never need to create a component instance directly—React takes care of this.

Finally, to create elements, use React.createElement(), JSX, or an element factory helper. Don’t write elements as plain objects in the real code—just know that they are plain objects under the hood.

React

React v15.0.1

Changelog #

React #

ReactDOM #

React v15.0

Upgrade Guide #

Installation #

Changelog #

Major changes #

document.createElement is in and data-reactid is out #

No more extra <span>s #

Rendering null now uses comment nodes #

Functional components can now return null too #

Improved SVG support #

Breaking changes #

No more extra <span>s #

React.cloneElement() now resolves defaultProps #

ReactPerf.getLastMeasurements() is opaque #

Removed deprecations #

New deprecations, introduced with a warning #

New helpful warnings #

Notable bug fixes #

Other improvements #

React v0.14.8

Changelog #

React #

React v15.0 Release Candidate 2

Installation #

React v15.0 Release Candidate

Upgrade Guide #

Installation #

Changelog #

Major changes #

document.createElement is in and data-reactid is out #

No more extra <span>s #

Rendering null now uses comment nodes #

Improved SVG support #

Breaking changes #

New deprecations, introduced with a warning #

New helpful warnings #

Notable bug fixes #

New Versioning Scheme

Bring Everyone Along #

Introducing Minor Releases #

What Happened to 1.0.0? #

Breaking Changes #

Avoiding The Major Cliff #

Discontinuing IE 8 Support in React DOM

(A => B) !=> (B => A)

React v0.14.4

Changelog #

React #

React DOM #

React Perf Add-on #

React Components, Elements, and Instances

Managing the Instances #

Elements Describe the Tree #

DOM Elements #

Component Elements #

Components Encapsulate Element Trees #

Components Can Be Classes or Functions #

Top-Down Reconciliation #

Summary #

Further Reading #

`document.createElement` is in and `data-reactid` is out #

No more extra `<span>`s #

Rendering `null` now uses comment nodes #

Functional components can now return `null` too #

No more extra `<span>`s #

`React.cloneElement()` now resolves `defaultProps` #

`ReactPerf.getLastMeasurements()` is opaque #

`document.createElement` is in and `data-reactid` is out #

No more extra `<span>`s #

Rendering `null` now uses comment nodes #