Document how React treats different attributes

[bvaughn]

This issue was originally reported by @MMeent via facebook/react/issues/9220

Please refer to the original issue for the related discussion thread.

Text of original issue:

As of #9106 there are quite a lot of tests for HTML's boolean properties on tags. According to these tests HTML properties should get rendered into empty strings or not set, e.g. <div hidden={true} /> should render to <div hidden="" /> and <div hidden={false} /> should render to <div />.

But when I look further, there are other tests which do similar things: <a href={true} /> should render to <a href="true" />. This means that if I take true as my property value, I will not know what the result will be.

The issue being: React currently does not have a clearly-defined and documented way with which they handle their props. Could the docs be updated to specify which type of prop will result in what? e.g. "any number gets parsed to a string (using Number.toString()), an object gets stringified by using arg => Object.entries(arg).map(([key, val]) => ${key}: ${val};).join(), and booleans toggle the property."

In short, these are the bugs/undocumented features/contradictions that the tests expect to happen, plus my expectations:

• prop={true} gets parsed to prop="" or prop="true" for select properties
  expected: either prop="" or prop="prop", not both // as per checked=checked HTML standard
• prop="" gets parsed as prop="" or
  expected: prop=""
• prop="prop" might get parsed as either prop="prop", prop="" or even
  expected: prop="prop"
• prop="foo" => prop="" or prop="foo"
  expected: prop="foo"
• prop={false} => or prop="false"
  expected:
• prop={['foo', 'bar']} => prop="" or prop="foo,bar" (hand-tested, no automatic test available)
  expected: prop="foo bar"
• prop={{foo: 'bar', baz: 5}} => prop="" or prop="foo: bar; baz: 5;" or prop="[object Object]" (hand-tested, no automatic test available)
  expected: prop="foo: bar; baz: 5" // as per style object transform

Hacky showcase: https://jsfiddle.net/ox8a7vfe/3/

Are these features or are these bugs?

If they are bugs, and work is going to be done on the props value parsing, then the following might be a nice addition:

• prop={{foo: true, bar: true, baz: false}} => prop="foo bar" // render all true keys, disregard false keys, like classNames.

[mrscobbler]

It looks like this blog post: https://reactjs.org/blog/2017/09/08/dom-attributes-in-react-16.html addresses a lot of the concerns in this particular issue.

Do we want to create a new docs page that summarizes what the blog post talks about and reference the blog post?

[bvaughn]

Perhaps, or perhaps we could add to this page: https://reactjs.org/docs/dom-elements.html

To be honest, I moved this issue from the old repo over the weekend along with a lot of others. I didn't read too deeply into it.

Would you be interested in working on this @mrscobbler ?

[mrscobbler]

Sure! I can work on it. I think adding to the existing page would be great.

[bvaughn]

This issue is all yours! 😄

I've added an "in-progress" label so that others will know not to start work on the issue. If you change your mind about the issue, no worries! Just let me know so that I can remove the label and free it up for someone else to claim.

Cheers!

[bvaughn]

Hey @mrscobbler! Just wanting to confirm that this issue is still being worked on.

No hurry of course. I'm just going through in-progress issues to see if any have been dropped. 😄

[mrscobbler]

Yes! Still planning on working on it. I'll make sure to comment on this if for some reason I can't get to it.

[bvaughn]

Great! Thanks!

[ManitejChowdary1]

Hello i would like to contribute to this

[suii2210]

Hi! I would like to work on this issue.

My plan:

• Add a new subsection to src/content/learn/describing-the-ui.md called "How React Handles HTML Attributes".
• Document the differences between HTML attributes and JSX props (className, htmlFor, boolean attributes, inline styles, data/aria attributes, unknown attributes).
• Include clear examples and align the tone with the existing docs.

Please let me know if this approach is okay, or if you prefer this to be added in a different page.

[suii2210]

Hi! I would like to work on this issue.

My plan:

• Add a new subsection to src/content/learn/describing-the-ui.md called "How React Handles HTML Attributes".
• Document the differences between HTML attributes and JSX props (className, htmlFor, boolean attributes, inline styles, data/aria attributes, unknown attributes).
• Include clear examples and align the tone with the existing docs.

Please let me know if this approach is okay, or if you prefer this to be added in a different page.

Correction: The subsection will actually be added to src/content/learn/writing-markup-with-jsx.md instead of describing-the-ui.md, since this page specifically covers JSX markup.