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.

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:

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.

Upgrading to 0.12

React With JSX

If you use the React specific JSX transform, the upgrade path is simple. Just make sure you have React in scope.

// If you use node/browserify modules make sure// that you require React into scope.var React =require('react');

React’s JSX will create the ReactElement for you. You can continue to use JSX with regular classes:

NOTE: React’s JSX will not call arbitrary functions in future releases. This restriction is introduced so that it’s easier to reason about the output of JSX by both the reader of your code and optimizing compilers. The JSX syntax is not tied to React. Just the transpiler. You can still use the JSX spec with a different transpiler for custom purposes.

React Without JSX

If you don’t use JSX and just call components as functions, you will need to explicitly create a factory before calling it:

Third-party Languages

Languages with static typing that don’t need validation (e.g. Om in ClojureScript), and production level compilers will be able to generate these objects inline instead of going through the validation step. This optimization will allow significant performance improvements in React.

Your Thoughts and Ideas

We’d love to hear your feedback on this API and your preferred style. A plausible alternative could be to directly inline objects instead of creating factory functions:

This moves the noise down into the render method though. It also doesn’t provide a hook for dynamic validation/type checking so you’ll need some other way to verify that it’s safe.

NOTE: This won’t work in this version of React because it’s conflicting with other legacy APIs that we’re deprecating. (We temporarily add a element._isReactElement = true marker on the object.)

The Next Step: ES6 Classes

After 0.12 we’ll begin work on moving to ES6 classes. We will still support React.createClass as a backwards compatible API. If you use an ES6 transpiler you will be able to declare your components like this:

exportclassMyComponent{render(){...}};

This upcoming release is a stepping stone to make it as easy as this. Thanks for your support.