RFC: Plan for Attributes in React 16

[gaearon]

Note: the final plan has changed. Refer to https://facebook.github.io/react/blog/2017/09/08/dom-attributes-in-react-16.html for details on what ends up in React 16.

---

This is a more formal conclusion of the discussion in #7311.
It is mostly (not yet fully) implemented by #10385.

This is meant to address #140.

I wrote this doc but it’s mostly based on discussion with @nhunzaker. I decided to write it in an attempt to formalize the behavior we want, so that if there are bugs, we can refer back to this.

Current Behavior

React only lets you use “approved” camelCase properties that look organic in JavaScript:

// No warning
<div className />           // => <div class />
<img srcSet />              // => <img srcset />
<svg enableBackground />    // => <svg enable-background />

// Warns
<div class />               // => <div />
<img srcset />              // => <img />
<svg enable-background />   // => <svg />

There are two downsides to this.

Problem: Custom Attributes

You can’t pass custom, non-standard, library-specific, or not-yet-standardized attributes:

// Warns
<input nwdirectory />      // => <input />
<div ng-app />             // => <div />
<div inert />              // => <div />

This is a very popular feature request.

Problem: Maintaining a Whitelist

We currently have to maintain a whitelist of all allowed attributes, and use it even in the production build.
By being more permissive, we can drop ReactDOM size by 7% post-min/gzip without any changes to app code.

Guiding Principles

If we change the current behavior, there’s a few existing principles we want to preserve:

• Code should behave identically in development and production. This one is pretty obvious but it constraints what we can do with the whitelist.
• Existing applications should keep on working. We are okay getting more permissive and passing more attributes through to the DOM, but we don’t want to change React DOM APIs at this point.
• There should be one obviously valid way to supply a property to component. For example, allowing both class and className would be ambiguous and confusing to component authors.
• We should maintain the spirit of JavaScript-centric API. Our users have already bought into the idea that it is more important for props to be consistent when used in JavaScript, than to match the HTML/SVG specs. We don’t want to change this now.

I think there is a compromise that lets us solve the problems above without deviating from these principles.

Proposed Behavior: Overview

We drop a large part of the whitelist, but we make the behavior less strict.
These used to be ignored due to wrong casing, but now will be passed through:

<div srcset />      // works but warns
<div classname />   // works but warns
<svg CalcMode />    // works but warns

Instead of being omitted, they will only emit a warning now.
However, we still don’t pass through attributes that differ in more than casing from React version:

<div class />            // doesn't work, warns
<div accept-charset />   // doesn't work, warns
<svg stroke-dasharray /> // doesn't work, warns

This lets us drop 7% of ReactDOM bundle size and keep most of the whitelist for development only.

Proposed Behavior: In Depth

Let’s say reactAttr is the attribute name you use in React, and domAttr is its name in HTML/SVG specs.
Our whitelist is a map from reactAttr to domAttr.

In React 15, it might look like this:

reactAttr	domAttr
className	class
srcSet	srcset
acceptCharset	accept-charset
arabicForm	arabic-form
strokeDashArray	stroke-dasharray
calcMode	calcMode

Proposed Changes to the Whitelist

We remove any attributes where lowercase(reactAttr) === lowercase(domAttr) and don’t have special behavior. In other words, we delete any attributes that “just work” in regular HTML.

reactAttr	domAttr
className	class
srcSet	srcset
acceptCharset	accept-charset
arabicForm	arabic-form
strokeDashArray	stroke-dasharray
calcMode	calcMode

(This is where we get 7% size savings.)
We still keep the full attribute whitelist in DEV mode for warnings.

Proposed Changes to the Algorithm

Let’s say givenAttr is the attribute in user’s JSX.
We follow these steps now:

Step 1: Check if there exists a reactAttr in the whitelist equal to the givenAttr.

If it there is a match, use the corresponding domAttr name from the whitelist and exit.
For example:

<div className />        // => <div class />
<div acceptCharset />    // => <div accept-charset />
<svg strokeDashArray />  // => <svg stroke-dasharray />

This matches behavior in 15.
If there is no match, continue.

Step 2: Check if there exists a domAttr in the whitelist that lowercase(domAttr) === lowercase(givenAttr)

We’re trying to determine if the user was using a DOM version of attribute that is sufficiently different from the one suggested by React (that is, by more than casing).

In this case, don’t render anything, warn and exit.

<div class />            // => <div /> + warning
<div accept-charset />   // => <div /> + warning
<svg stroke-dasharray /> // => <svg /> + warning

So far this matches behavior in 15.

Note that this does not catch the cases that were sufficiently similar that we excluded them from the whitelist. For example:

<div srcset />           // not in the whitelist, continue the algorithm
<div classname />        // not in the whitelist, continue the algorithm
<svg CalcMode />         // not in the whitelist, continue the algorithm

This is because we don’t keep them in the whitelist anymore.
If we hit such case, continue below.

Step 3: If the value type is valid, write givenAttr to the DOM, with a warning if it deviates from React canonical API.

This is where we deviate from 15.
If we reached this stage, we render it to the DOM anyway, which may or may not be successful:

<div srcset />           // => <div srcset /> (works) + warning
<div classname />        // => <div classname /> (not very useful) + warning
<svg CalcMode  />        // => <svg CalcMode /> (works) + warning

We only render strings and numbers.

If the value is of a different type, we skip it and warn.
For numbers, we also warn (but still render it) if the value coerced to string is 'NaN'.

Success now depends on whether DOM accepts such an attribute.

However, we will still warn if there is a reactAttr that lowercase(reactAttr) === lowercase(givenAttr).

In other words, we warn if there is a canonical React API that differs in casing, such as for all above cases.

This step also captures the new requirement. Any completely unknown attributes will happily pass through:

<input nwdirectory />      // => <input nwdirectory />
<div ng-app />             // => <div ng-app />
<div inert />              // => <div inert />

Other Considerations

• ARIA and DATA attributes still pass through. The validation of ARIA attributes has moved to be development-only. We allow (but warn on) any unexpected ARIA attributes or attributes that seem like ARIA attributes (e.g. ariaSomething). This is a minor deviation from “pass everything through” approach but seems sensible.
• Handling of custom element attributes has not changed.
• Handling of special attributes (e.g. style) has not changed.
• Note how with this approach, adding support for a new DOM attribute is still possible in a minor version as long as it’s only different in casing. People would get a warning about the new canonical name for it, but at least the old name (which they might have been using) would still work. Unlike the case where we completely disallow a second name for known attributes but allow custom attributes in general.

[gaearon]

One thing we haven’t quite worked out yet: should we pass numbers and booleans through.
Benefits of doing so:

• We can drop more things from the whitelist.
• It matches the intuitive behavior (based on experience with standard props which allow that).

Downsides:

• For booleans, "false" might be interpreted as truthy by the browser in some cases.

[gaearon]

We have (mostly) settled on this tradeoff:

• We pass strings and numbers through. We don’t pass booleans (but we warn about them).
• We coerce numbers to strings before passing them through.
• If the value was a number, and the coerced string is 'NaN', we should warn in development (but still set it).

@sebmarkbage wants to look into a few more corner cases but this is likely the last tweak.

[aweary]

We pass strings and numbers through. We don’t pass booleans (but we warn about them).

Can you clarify what you mean by not passing booleans through? What are we warning about?

[gaearon]

<div myCustomAttr={true} />

would not render it to the DOM and would display a warning about it not being a string or number.

The concern is that browser APIs are not consistent about what "false" means. So coercing to string might not work for future boolean attributes. If React was to pass them through before it is aware of them, it could potentially render value for ={false} that browser would interpret as truthy. And then when we actually add support for it, it would "flip" for people already relying on wrong behavior. Being a breaking change.

This doesn’t affect known boolean attributes. We will still keep them in the whitelist. So you can keep passing false to them.

[aweary]

This doesn’t affect known boolean attributes. We will still keep them in the whitelist.

That's what I was confused about, thanks.

[sebmarkbage]

Thoughts on special casing custom elements? If there is a property on the element with the same name, then use the property instead of the attribute?

[gaearon]

I’d love to see that! But let’s discuss separately? Since there is already a lot to take in here, and @nhunzaker is probably close to exhaustion from working on this 😛

[gaearon]

Although it would be nice to get changes to custom elements in 16 now that we have a chance.

[gaearon]

For custom elements, let’s follow what Preact does? If a property is defined, use a property, otherwise use attribute. But for objects/arrays always use properties.

[sebmarkbage]

Even for objects/arrays, we should only use properties if one exist. But we should warn and not set if none exist.

The problem with detecting properties is that in can catch a native property on the super class (e.g. Element.prototype) which could prevent browsers from adding properties with those names later. We can't detect hasOwnProperty since many will be getter/setters.

[aweary]

What about objects with custom toString methods? Those should still be passed through.

[gaearon]

What about objects with custom toString methods? Those should still be passed through.

Are you talking about custom elements or regular elements (focus of this issue)?

Let’s keep this issue focused on regular elements. One doesn’t block the other, and I don’t want bikeshedding over custom elements to black landing this. :-)

[sebmarkbage]

Both. :)

[gaearon]

I don’t think we should ever let toString() be called.

For custom elements I’d expect we pass them (as objects) if property exists, and don’t pass otherwise. If you want it to be an attribute IMO you should explicitly call toString() to express your intention.

For regular elements we don’t pass them through and always warn. Since you could be accidentally spreading something from a parent component, and toString() could be dangerous (e.g. very expensive or throws).