Streamlining React Elements

Streamlining React Elements

Written by jatin | Published a month ago

React v0.13 is right around the corner and so we wanted to discuss some upcoming changes to ReactElement. In particular, we added several warnings to some esoteric use cases of ReactElement. There are no runtime behavior changes for ReactElement - we’re adding these warnings in the hope that we can change some behavior in v0.14 if the changes are valuable to the community.

If you use React in an idiomatic way, chances are, you’ll never see any of these warnings. In that case, you can skip this blog post. You can just enjoy the benefits! These changes will unlock simplified semantics, better error messages, stack traces and compiler optimizations!

Immutable Props

In React 0.12, the props object was mutable. It allows you to do patterns like this:

var element = <Foo bar={false} />;
if (shouldUseFoo) { = 10; = true;

The problem is that we don’t have a convenient way to tell when you’re done mutating.

Problem: Mutating Props You Don’t Own

If you mutate something, you destroy the original value. Therefore, there is nothing to diff against. Imagine something like this:

var element = this.props.child;
element.props.count = this.state.count;
return element;

You take a ReactElement through props.child and mutate its property before rendering it. If this component’s state updates, this render function won’t actually get a new ReactElement in props.child. It will be the same one. You’re mutating the same props.

You could imagine that this would work. However, this disables the ability for any component to use shouldComponentUpdate. It looks like the component never changed because the previous value is always the same as the next one. Since the DOM layer does diffing, this pattern doesn’t even work in this case. The change will never propagate down to the DOM except the first time.

Additionally, if this element is reused in other places or used to switch back and forth between two modes, then you have all kinds of weird race conditions.

It has always been broken to mutate the props of something passed into you. The problem is that we can’t warn you about this special case if you accidentally do this.

Problem: Too Late Validation

In React 0.12, we do PropType validation very deep inside React during mounting. This means that by the time you get an error, the debugger stack is long gone. This makes it difficult to find complex issues during debugging. We have to do this since it is fairly common for extra props to be added between the call to React.createElement and the mount time. So the type is incomplete until then.

The static analysis in Flow is also impaired by this. There is no convenient place in the code where Flow can determine that the props are finalized.

Solution: Immutable Props

Therefore, we would like to be able to freeze the element.props object so that it is immediately immutable at the JSX callsite (or createElement). In React 0.13 we will start warning you if you mutate element.props after this point.

You can generally refactor these pattern to simply use two different JSX calls:

if (shouldUseFoo) {
  return <Foo foo={10} bar={true} />;
} else {
  return <Foo bar={false} />;

However, if you really need to dynamically build up your props you can just use a temporary object and spread it into JSX:

var props = { bar: false };
if (shouldUseFoo) { = 10; = true;
return <Foo {...props} />;

It is still OK to do deep mutations of objects. E.g:

return <Foo nestedObject={this.state.myModel} />;

In this case it’s still ok to mutate the myModel object in state. We recommend that you use fully immutable models. E.g. by using immutable-js. However, we realize that mutable models are still convenient in many cases. Therefore we’re only considering shallow freezing the props object that belongs to the ReactElement itself. Not nested objects.

Solution: Early PropType Warnings

We will also start warning you for PropTypes at the JSX or createElement callsite. This will help debugging as you’ll have the stack trace right there. Similarly, Flow also validates PropTypes at this callsite.

Note: There are valid patterns that clones a ReactElement and adds additional props to it. In that case these additional props needs to be optional.

var element1 = <Foo />; // extra prop is optional
var element2 = React.addons.cloneWithProps(element1, { extra: 'prop' });


In React each child has both a “parent” and an “owner”. The owner is the component that created a ReactElement. I.e. the render method which contains the JSX or createElement callsite.

class Foo {
  render() {
    return <div><span /></div>;

In this example, the owner of the span is Foo but the parent is the div.

There is also an undocumented feature called “context” that also relies on the concept of an “owner” to pass hidden props down the tree.

Problem: The Semantics are Opaque and Confusing

The problem is that these are hidden artifacts attached to the ReactElement. In fact, you probably didn’t even know about it. It silently changes semantics. Take this for example:

var foo = <input className="foo" />;
class Component {
  render() {
    return bar ? <input className="bar" /> : foo;

These two inputs have different owners, therefore React will not keep its state when the conditional switches. There is nothing in the code to indicate that. Similarly, if you use React.addons.cloneWithProps, the owner changes.

Problem: Timing Matters

The owner is tracked by the currently executing stack. This means that the semantics of a ReactElement varies depending on when it is executed. Take this example:

class A {
  render() {
    return <B renderer={text => <span>{text}</span>} />;
class B {
  render() {
    return this.props.renderer('foo');

The owner of the span is actually B, not A because of the timing of the callback. This all adds complexity and suffers from similar problems as mutation.

Problem: It Couples JSX to React

Have you wondered why JSX depends on React? Couldn’t the transpiler have that built-in to its runtime? The reason you need to have React.createElement in scope is because we depend on internal state of React to capture the current “owner”. Without this, you wouldn’t need to have React in scope.