[New Docs] "DOM Elements" reference and cleanup by lacker · Pull Request #7983 · facebook/react

lacker · 2016-10-14T23:36:51Z

This creates one "DOM Elements" reference doc whose goal is to explain all the little DOM tweaks that React makes. This doc replaces a few different previous reference docs, and also a number of tips.

I also removed all the tips and reference docs that are now superceded. All the tips are dealt with now, and except for the error decoder, all the old docs have some PR out that replaces them.

lacker · 2016-10-14T23:37:41Z

gaearon · 2016-10-15T11:50:53Z

docs/docs/reference-dom-elements.md


-The following HTML elements are supported in `React.DOM.*`:
+The `checked` attribute is supported by `<input>` components of type `checkbox` or `radio`. You can use it to set whether the component is checked. This is useful for building controlled components.
+


Do we have any place in new docs where controlled vs uncontrolled is explained?

That's pending on the "forms" doc existing. @ericnakagawa said he'd have that in a PR later today

gaearon · 2016-10-15T11:52:59Z

docs/docs/reference-dom-elements.md

+
+### className
+
+Since `class` is a reserved word in JavaScript, React elements use `className` instead.


Gotcha: except if you use web components.

Also, the real reason is just historical. These days it being reserved word doesn't matter and many libraries use class for the same purpose without any issues.

So maybe it's fine to just punt on explaining instead of blaming JavaScript.

ok I just stopped trying to explain

gaearon · 2016-10-15T11:53:49Z

docs/docs/reference-dom-elements.md

+### dangerouslySetInnerHTML
+
+`dangerouslySetInnerHTML` is React's replacement for using `innerHTML` in the browser DOM. In general, setting HTML from code is risky because it's easy to inadvertently expose your users to a [cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) attack. So, you can set HTML directly from React, but you have to type out `dangerouslySetInnerHTML` to remind yourself that it's dangerous. For example:
+


Let's also mention the result must have __html field for extra explicitness? Otherwise it's not clear what it means.

ok added this mention

gaearon · 2016-10-15T12:00:32Z

docs/docs/reference-dom-elements.md

+
+### key
+
+`key` in React doesn't correspond to anything in HTML. It's an optional unique identifier for components in lists. Assigning it a key that persists makes sure the component stays. You can read more [here](/react/docs/reconciliation.html).


It's not quite optional. React loudly complains if it is missing.

Giving it a key just means component gets reordered efficiently. It does not determine whether it "stays".

just removed this section as mentioned below

gaearon · 2016-10-15T12:02:25Z

docs/docs/reference-dom-elements.md

+
+The `onChange` event behaves as you would expect it to: whenever a form field is changed, this event is fired. We intentionally do not use the existing browser behavior because `onChange` is a misnomer for its behavior and React relies on this event to handle user input in real time.
+
+### ref


Can we group key, ref and put them at the beginning?

They have completely different semantics and are handled by React itself. They also work on custom components unlike any other attributes here.

Ah, you're right - actually I don't think key and ref belong in this document at all. This document is supposed to just be differences between the regular DOM, and the React DOM, and key and ref are more like React features than things related to DOM elements. Since we already have other docs that go into great detail about key and ref, I just removed this brief sections.

gaearon · 2016-10-15T12:04:19Z

docs/docs/reference-dom-elements.md

+
+### suppressContentEditableWarning
+
+This is used to suppress the warning when using `contentEditable` and `children`.


It's confusing why warning exists then. Maybe mention "by projects like Draft.js that manage contentEditable manually"

gaearon · 2016-10-15T12:05:00Z

docs/docs/reference-dom-elements.md

+
+### value
+
+The `value` attribute is supported by `<input>` and `<textarea>` components. You can use it to set the value of the component. This is useful for building controlled components.


Maybe also good to mention defaultValue and defaultChecked as their uncontrolled equivalents?

gaearon · 2016-10-15T12:07:12Z

docs/docs/reference-dom-elements.md

 ```

-#### SVG elements
+## All Supported SVG Elements


This is incorrect. The list below is the list of SVG elements for which we have shortcuts in discouraged React.DOM factories.

However if you use JSX (of if you pass strings to createElement and avoid React.DOM factories), all SVG elements are supported out of the box. There is no whitelist for them.

Ah OK - I did not see that those were different things. In that case I think this section should just not go into the doc, along with the React.DOM-specific stuff. Removed it

lacker · 2016-10-17T20:24:10Z

OK i responded to all comments

gaearon

Accepting with nits

gaearon · 2016-10-17T20:43:13Z

docs/docs/reference-dom-elements.md

+### className

-#### SVG elements
+Most React elements use `className` instead of `class`. Web Components still use `class`.


"Most React elements" is a bit weird.
Maybe:

To specify CSS class, use the className attribute. This applies to all regular DOM and SVG elements like <div>, <a>, and others.

If you use React with Web Components (which is uncommon), pass class instead.

gaearon · 2016-10-17T20:43:44Z

docs/docs/reference-dom-elements.md

-The following SVG elements are supported in `React.DOM.*`:
+### dangerouslySetInnerHTML

+`dangerouslySetInnerHTML` is React's replacement for using `innerHTML` in the browser DOM. In general, setting HTML from code is risky because it's easy to inadvertently expose your users to a [cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) attack. So, you can set HTML directly from React, but you have to type out `dangerouslySetInnerHTML` and pass an object with a `__html` key,to remind yourself that it's dangerous. For example:


Missing space before "to remind"

gaearon · 2016-10-17T20:46:12Z

docs/docs/reference-dom-elements.md

+
+function HelloWorldComponent() {
+  return <div style={divStyle}>Hello World!</div>;
+}


Can we have two separate examples here? One should be simple and show basic style usage. The second can be preceded by "Note that styles are not autoprefixed. To support older browsers, you need to supply corresponding style properties."

lacker added 6 commits October 14, 2016 14:59

glossary is superceded

caf51a5

remove some superceded tips

e6befb6

remove no-longer-existent stuff from the bar

5318e5a

make a DOM Elements reference

31d4868

remove superceded stuff

6e9edb7

remove all tips

bfcb3d2

facebook-github-bot added GH Review: review-needed CLA Signed labels Oct 14, 2016

hramos changed the title ~~"DOM Elements" reference and cleanup~~ [New Docs] "DOM Elements" reference and cleanup Oct 15, 2016

gaearon reviewed Oct 15, 2016

View reviewed changes

lacker added 4 commits October 17, 2016 13:07

classname

6575a6e

mention __html

eef5e5c

element tweaks

2b81bca

responding to things

a5e1b64

gaearon approved these changes Oct 17, 2016

View reviewed changes

lacker added 3 commits October 18, 2016 16:07

words

e22e3f7

more detail on style camelcasing

7aa907b

merge

08165f9

lacker merged commit 89fbf08 into facebook:new-docs Oct 18, 2016

lacker deleted the cleanup branch October 18, 2016 23:21


		The following HTML elements are supported in `React.DOM.*`:
		The `checked` attribute is supported by `<input>` components of type `checkbox` or `radio`. You can use it to set whether the component is checked. This is useful for building controlled components.


		### className

		Since `class` is a reserved word in JavaScript, React elements use `className` instead.

		### dangerouslySetInnerHTML

		`dangerouslySetInnerHTML` is React's replacement for using `innerHTML` in the browser DOM. In general, setting HTML from code is risky because it's easy to inadvertently expose your users to a [cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) attack. So, you can set HTML directly from React, but you have to type out `dangerouslySetInnerHTML` to remind yourself that it's dangerous. For example:


		### key

		`key` in React doesn't correspond to anything in HTML. It's an optional unique identifier for components in lists. Assigning it a key that persists makes sure the component stays. You can read more [here](/react/docs/reconciliation.html).


		The `onChange` event behaves as you would expect it to: whenever a form field is changed, this event is fired. We intentionally do not use the existing browser behavior because `onChange` is a misnomer for its behavior and React relies on this event to handle user input in real time.

		### ref


		### suppressContentEditableWarning

		This is used to suppress the warning when using `contentEditable` and `children`.


		### value

		The `value` attribute is supported by `<input>` and `<textarea>` components. You can use it to set the value of the component. This is useful for building controlled components.

Conversation

lacker commented Oct 14, 2016

Uh oh!

lacker commented Oct 14, 2016

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lacker commented Oct 17, 2016

Uh oh!

gaearon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants