Introducing React Elements

The upcoming React 0.12 tweaks some APIs to get us close to the final 1.0 API. This release is all about setting us up for making the ReactElement type really FAST, jest unit testing easier, making classes simpler (in preparation for ES6 classes) and better integration with third-party languages!

If you currently use JSX everywhere, you don’t really have to do anything to get these benefits! The updated transformer will do it for you.

If you can’t or don’t want to use JSX, then please insert some hints for us. Add a React.createFactory call around your imported class when you require it:

var MyComponent = React.createFactory(require('MyComponent'));

Everything is backwards compatible for now, and as always React will provide you with descriptive console messaging to help you upgrade.

ReactElement is the primary API of React. Making it faster has shown to give us several times faster renders on common benchmarks. The API tweaks in this release helps us get there.

Continue reading if you want all the nitty gritty details…

New Terminology

We wanted to make it easier for new users to see the parallel with the DOM (and why React is different). To align our terminology we now use the term ReactElement instead of descriptor. Likewise, we use the term ReactNode instead of renderable.

See the full React terminology guide.

Creating a ReactElement

We now expose an external API for programmatically creating a ReactElement object.

var reactElement = React.createElement(type, props, children);

The type argument is either a string (HTML tag) or a class. It’s a description of what tag/class is going to be rendered and what props it will contain. You can also create factory functions for specific types. This basically just provides the type argument for you:

var div = React.createFactory('div');
var reactDivElement = div(props, children);

Deprecated: Auto-generated Factories

Imagine if React.createClass was just a plain JavaScript class. If you call a class as a plain function you would call the component’s constructor to create a Component instance, not a ReactElement:

new MyComponent(); // Component, not ReactElement

React 0.11 gave you a factory function for free when you called React.createClass. This wrapped your internal class and then returned a ReactElement factory function for you.

var MyComponent = React.createFactory(
  class {
    render() {
      ...
    }
  }
);

In future versions of React, we want to be able to support pure classes without any special React dependencies. To prepare for that we’re deprecating the auto-generated factory.

This is the biggest change to 0.12. Don’t worry though. This functionality continues to work the same for this release, it just warns you if you’re using a deprecated API. That way you can upgrade piece-by-piece instead of everything at once.