JSX Docs: JSX In Depth and React Without JSX #7878

lacker · 2016-10-05T04:34:23Z

This creates two new documents. "JSX In Depth" attempts to describe all of JSX, covering the occasionally-relevant edge cases and weird bits. It should be a document you can go to, to get your weird JSX questions answered. "React Without JSX" just explains how to use React without JSX.

Some docs in the old site are now obsoleted. "JSX Spread Attributes" and "JSX Gotchas" along with a number of the JSX-specific tips are just part of "JSX In Depth" now.

I just removed the translations of the no-longer-there docs. Dunno what else to do with them.

Thanks @spicyj for answering a zillion of my JSX questions in person this afternoon ;-) But still I'm sure I am mis-explaining some things here, so I'd appreciate a sharp-eyed review of this content.

lacker · 2016-10-05T04:35:21Z

lacker · 2016-10-05T04:35:40Z

gaearon · 2016-10-05T08:00:08Z

docs/docs/jsx-in-depth.md

+transpiles into:
+
+```js
+React.createElement('div', {id: 'blorp'}, null)


Minor not: you'd almost never want to use the id attribute in React components. Maybe className?

gaearon · 2016-10-05T08:01:58Z

docs/docs/jsx-in-depth.md

+
+## HTML Tags and React Components
+
+The first part of a JSX tag determines the type of the JSX element.


"Of the React element"? We don't really say "JSX element" elsewhere.

Hm ok I stopped saying "JSX element".

Now that I read @spicyj comments I think it's fine (haha sorry). Since this is a doc about JSX specifically I think it's fine to say JSX Element.

gaearon · 2016-10-05T08:03:44Z

docs/docs/jsx-in-depth.md

+  return <MyComponent />;
+}
+```
+


Maybe add here:

"If you don't use a JavaScript bundler and added React as a script tag, it is already in scope as a React global."

gaearon · 2016-10-05T08:05:43Z

docs/docs/jsx-in-depth.md

+```js
+import React from 'react';
+import Settings from './settings';
+


I feel like this is a minefield because it only works if you use default exports in that file. Maybe shift the attention from imports to demonstrating this in one file? So that we don't have to explain how modules work in this document.

In general, "dot notation" for components is not popular and I think could live somewhere in the bottom of the document. We don't need to emphasize this, and other topics (such as how expressions and whitespace work) seem more valuable to me.

I ditched the import and cut it down to one example instead of two to de-emphasize it. I'd like to keep this here though because this section of the document is explaining "all the ways to specify the element type".

gaearon · 2016-10-05T08:06:07Z

docs/docs/jsx-in-depth.md

+import Settings from './settings';
+
+export default function() {
+  return <Settings.DatePicker barColor={'blue'} />;


Let's give names to all functions.

gaearon · 2016-10-05T08:07:36Z

docs/docs/jsx-in-depth.md

+
+export default function() {
+  // This code attempts to create an HTML <hello> tag and fails
+  return <hello {toWhat='World'} />


Unintentional braces

gaearon · 2016-10-05T08:08:47Z

docs/docs/jsx-in-depth.md

+  return <findComponent() />;
+}
+
+var MyComponent = findComponent();


Let's move this inside the function? That would be equivalent to your first example then.

gaearon · 2016-10-05T08:09:40Z

docs/docs/jsx-in-depth.md

+When you pass a string literal, its value is HTML-unescaped. So these two JSX expressions are equivalent:
+
+```js
+<MyComponent message="&lt;3" />


Today I learned

gaearon · 2016-10-05T08:11:43Z

docs/docs/jsx-in-depth.md

+
+A React component can't return multiple JSX elements, but a single JSX element can have multiple children, so if you want a component to render multiple things you can wrap it in a `div` like this.
+
+When you pass JSX as the children, `props.children` does not actually let you access the child component from the parent. Instead, it lets you access the return value of `React.createElement` calls using the `React.Children` helper library. Generally, accessing children in this way is only useful to return in a render function, rather than modifying or altering the children.


I don't understand this paragraph, can you rephrase (maybe with an example)

I'm just going to delete it - it probably belongs more appropriately in somewhere that discusses "components vs instances vs elements" rather than "all about jsx" because it's not really jsx-specific

gaearon · 2016-10-05T08:12:45Z

docs/docs/jsx-in-depth.md

+
+<div>{false}</div>
+
+<div>{null}</div>


This document should also include detailed information on how whitespace woks in JSX.

OK I added a section about whitespace

sophiebits · 2016-10-05T17:23:24Z

No tinyurl please -- no need to add another dependency.

keyz · 2016-10-05T17:36:49Z

docs/docs/jsx-in-depth.md

+  var todos = ['finish doc', 'submit pr', 'nag dan to review'];
+  return (
+    <ul>
+      {todos.map(renderItem)}


Since this is an array, each child should have a unique key prop.

An inquisitive reader would think: when don't want to do this instead of using <Item>?

In general we want to encourage people to create components rather than call functions directly. But I guess this is fine.

I don't have a good solution to this.

Maybe if we put map body inline as an arrow it is clearer that this pattern is mostly useful for one-liners.

keyz · 2016-10-05T17:49:02Z

docs/docs/jsx-in-depth.md

+function ListOfTenThings() {
+  return (
+    <Repeat>
+      {(index) => <div>This is item {index} in the list</div>}


<Repeat numTimes={10}>? :) Also missing key here.

keyz · 2016-10-05T17:54:57Z

docs/docs/jsx-in-depth.md

+  if (props.number % 2 == 0) {
+    word = 'even';
+  } else {
+    word = 'odd';


did you mean description = 'odd'?

sophiebits · 2016-10-05T18:39:27Z

docs/docs/jsx-in-depth.md

+Fundamentally, JSX just provides syntactic sugar for the `React.createElement(component, props, children)` function. The JSX code:
+
+```js
+<MyComponent prop1={'one'} prop2={'two'}>stuff</MyComponent>


It's a little weird to me that this uses {} since people don't ever do that in practice.

That, and let's use double quotes in JSX too since most popular styleguides do that. So it'll be prop1="one".

I would also like us to use more real-world over contrived examples. Like Button or Avatar instead of MyComponent or Foo.

sophiebits · 2016-10-05T18:52:37Z

docs/docs/jsx-in-depth.md

+}
+```
+
+If the element type starts with a lowercase letter, React will try to create a React element that maps directly to an HTML tag, rather than creating an element based on a custom component. In general, name your components starting with capital letters, and this will be fine. If you do have a component that starts with a lowercase letter, assign it to a capitalized variable before using it in JSX.


Can we do something closer to:

When an element type starts with a lowercase letter, it refers to a built-in component like <div> or <span> and results in a string 'div' or 'span' passed to React.createElement. Types that start with a capital letter like <Foo /> compile to React.createElement(Foo) and correspond to a component defined or imported in your JavaScript file.

We recommend naming components with a capital letter. If you do have a component that starts with a lowercase letter, assign it to a capitalized variable before using it in JSX.

I don't want to over-pivot on HTML/DOM in the JSX docs.

OK I just took this wording exactly

sophiebits · 2016-10-05T18:54:07Z

docs/docs/jsx-in-depth.md

+}
+```
+
+You cannot use a general expression as the React element type. If you do want to use a general expression to indicate the type of the element, just assign it to a capitalized variable first. For example, if you have a `findComponent()` function that returns a component, and you want to render one:


A more realistic example here would be

const storyComponents = { photo: <PhotoStory />, video: <VideoStory />, }; <storyComponents[this.props.storyType] />

This is where I most frequently see people actually having problems.

OK I switched to use an example like this

sophiebits · 2016-10-05T18:54:48Z

docs/docs/jsx-in-depth.md

+function NumberDescriber(props) {
+  var description;
+  if (props.number % 2 == 0) {
+    description = 'even';


Can we use an example where the branches each make a component? Maybe just <strong>even</strong>.

sophiebits · 2016-10-05T18:55:54Z

docs/docs/jsx-in-depth.md

+<MyTextBox autocomplete={true} />
+```
+
+In general, we don't recommend using this. It's more consistent to just use the second form and explicitly pass `true`. This behavior is just there so that it matches the behavior of HTML.


In general, we don't recommend using this form because it can be confused with the ES6 object shorthand {autocomplete} which is short for {autocomplete: autocomplete} rather than {autocomplete: true}.

sophiebits · 2016-10-05T19:01:21Z

docs/docs/jsx-in-depth.md

+
+This usage is not common, but it works if you want to stretch what JSX is capable of.
+
+`false` or `null` are valid children. They simply don't render. These JSX expressions will all render to the same thing:


It would be helpful to explain why this is useful <div>{showHeader && <Header />}<Content /></div>.

P.S. true also is ignored. This is not JSX but is React DOM and might not belong here.

I like your example. Added

Hmm, this seems like a super logical place to mention that true is ignored... I'll just mention it here.

I meant all of true/false/null being ignored is a React DOM thing, not a JSX thing.

sophiebits · 2016-10-05T19:02:03Z

docs/docs/react-without-jsx.md

+can also be written without JSX:
+
+```js
+class Hello extends React.Component {


I know you show it right below, but can we do const e = in every example except when we're specifically discussing what JSX compiles to? It's the recommended way to use createElement.

This code block is the only place we use React.createElement and I'd like to have it in one place so it's clear that it doesn't compile to the 'e' thing. How about I make this part specifically say, you can compile out the JSX

sophiebits · 2016-10-05T19:02:23Z

docs/docs/react-without-jsx.md

+  }
+}
+
+ReactDOM.render(<Hello toWhat={'World'} />,


fb style, please

ReactDOM.render( <Hello ... />, document... );

sophiebits · 2016-10-05T19:02:42Z

docs/docs/react-without-jsx.md

+  }
+}
+
+ReactDOM.render(React.createElement(Hello, {toWhat: 'World'}, null),


fb indentation

sophiebits · 2016-10-05T19:03:03Z

docs/downloads/single-file-example.html

  <head>
    <meta charset="UTF-8" />
-    <title>Hello React World!</title>
+    <title>hello</title>


intentional?

Yeah this is intentional because downloading the file from your browser will default to naming it the title of the page, and if there's spaces and a ! in it, it's annoying to open it in CLI editors. At least that's how I felt when actually using it to try out some examples.

Oh. Can we just put a download attribute on the link to this file instead?

gaearon · 2016-10-05T20:11:05Z

docs/docs/jsx-in-depth.md

+permalink: docs/jsx-in-depth.html
+---
+
+Fundamentally, JSX just provides syntactic sugar for the `React.createElement(component, props, children)` function. The JSX code:


Can make this ...children? It accepts variadic arguments.

gaearon · 2016-10-05T20:12:57Z

docs/docs/jsx-in-depth.md

+Fundamentally, JSX just provides syntactic sugar for the `React.createElement(component, props, children)` function. The JSX code:
+
+```js
+<MyComponent prop1={'one'} prop2={'two'}>stuff</MyComponent>


That, and let's use double quotes in JSX too since most popular styleguides do that. So it'll be prop1="one".

I would also like us to use more real-world over contrived examples. Like Button or Avatar instead of MyComponent or Foo.

gaearon · 2016-10-05T20:14:35Z

docs/docs/jsx-in-depth.md

+
+export default function MyRedComponent() {
+  return <MyComponent color="red" />;
+}


Same here: could be Button and DangerButton.

gaearon · 2016-10-05T20:15:36Z

docs/docs/jsx-in-depth.md

+
+If you don't use a JavaScript bundler and added React as a script tag, it is already in scope as a React global.
+
+You can also refer to a React component using dot-notation from within JSX. This is convenient if you have a single module that exports many React components. For example, if `MyComponents.DatePicker` is a component, you can invoke it directly from JSX with:


Nit: "use" rather than "invoke" because you won't actually be calling it

gaearon · 2016-10-05T20:17:25Z

docs/docs/jsx-in-depth.md

+  return <div>Hello {props.toWhat}</div>;
+}
+
+export default function HelloWorld() {


I think we shouldn't emphasize exports in examples unless we specifically mention module boundaries. It's fine to leave this as a function and presume that it gets rendered by something later.

gaearon · 2016-10-05T20:20:52Z

docs/docs/jsx-in-depth.md

+}
+```
+
+## Props in JSX


I'm conflicted about calling them props here.

If we are talking about JSX, "attributes" seems more correct. Attributes usually become props (for custom components). However key and ref are attributes obeying JSX rules that don't become props.

I don't feel strongly about this though. @spicyj What do you think?

gaearon · 2016-10-05T20:22:59Z

docs/docs/jsx-in-depth.md

+<MyComponent message={"<3"} />
+```
+
+This behavior is usually not relevant. It's useful for `children`, but not for most props. It's only mentioned here for completeness.


Nit: it is not obvious to me how this is useful for children, or what children "content" prop has to do with explicitly specified string literal attributes.

I tweaked the wording a bit. AFAICT this behavior is useful so that

Foo & Bar

works the same way in HTML and in JSX - you need an unescape because JSX will re-escape it later. I'm guessing someone implemented this for children and just implemented it for all string literal props at the same time? Dunno though. Seems like a historical wart.

Yeah, i'm not sure what children has anything to do here :)

The two times I ran into are:
(1) trying to write a "

<C prop="this is \"something\"" />

is a syntax error as the \ is not escaping the "

(2) trying to use an unicode sequence

<C prop="\u2192" />

will not display the unicode →, it's just going to display \u2192. Instead you need to do

<C prop="→" /> // or <C prop={"\u2192"} />

gaearon · 2016-10-05T20:27:16Z

docs/docs/jsx-in-depth.md

+  var todos = ['finish doc', 'submit pr', 'nag dan to review'];
+  return (
+    <ul>
+      {todos.map(renderItem)}


An inquisitive reader would think: when don't want to do this instead of using <Item>?

In general we want to encourage people to create components rather than call functions directly. But I guess this is fine.

I don't have a good solution to this.

gaearon · 2016-10-05T20:27:59Z

docs/docs/jsx-in-depth.md

+  var todos = ['finish doc', 'submit pr', 'nag dan to review'];
+  return (
+    <ul>
+      {todos.map(renderItem)}


Maybe if we put map body inline as an arrow it is clearer that this pattern is mostly useful for one-liners.

gaearon · 2016-10-05T20:30:36Z

docs/docs/jsx-in-depth.md

+  );
+}
+```
+


Maybe add another post-explainer here: Children passed to a custom component can be anything as long as that component transforms them into something React can understand before rendering.

OK - yeah I didn't intend that part to explain functions, only to explain loops, so I turned it into a one-liner. Also added that post-explainer

vjeux · 2016-10-05T21:12:04Z

docs/docs/jsx-in-depth.md

+You can also use the self-closing form of the tag if there are no children. So:
+
+```js
+<div className={'blorp'} />


nit: "blorp"

i just switched this to be more realistic rather than "blorp"

vjeux · 2016-10-05T21:13:54Z

docs/docs/jsx-in-depth.md

+}
+
+export default function BlueDatePicker() {
+  return <MyComponents.DatePicker color={'blue'} />;


vjeux · 2016-10-05T21:21:39Z

docs/docs/jsx-in-depth.md

+<MyComponent message={"<3"} />
+```
+
+This behavior is usually not relevant. It's useful for `children`, but not for most props. It's only mentioned here for completeness.


Yeah, i'm not sure what children has anything to do here :)

The two times I ran into are:
(1) trying to write a "

<C prop="this is \"something\"" />

is a syntax error as the \ is not escaping the "

(2) trying to use an unicode sequence

<C prop="\u2192" />

will not display the unicode →, it's just going to display \u2192. Instead you need to do

<C prop="→" /> // or <C prop={"\u2192"} />

vjeux · 2016-10-05T21:24:22Z

docs/docs/jsx-in-depth.md

+```js
+<MyComponent>foo</MyComponent>
+
+<MyComponent>{"foo"}</MyComponent>


nit: we use single quote for js strings

OK I just removed that "oh but this makes sense for children" comment.

vjeux · 2016-10-05T21:41:31Z

🎉

sophiebits · 2016-10-05T21:49:40Z

docs/docs/react-without-jsx.md

+  }
+}
+
+ReactDOM.render(React.createElement(Hello, {toWhat: 'World'}, null),


fb indentation

sophiebits · 2016-10-05T21:49:55Z

docs/docs/react-without-jsx.md

+```js
+class Hello extends React.Component {
+  render() {
+    return React.createElement('div', null, `Hello ${this.props.toWhat}`);


nit: can we do 'Hello ', this.props.toWorld) so it's a faithful compilation?

sophiebits · 2016-10-05T21:50:40Z

docs/docs/react-without-jsx.md

+```js
+var e = React.createElement;
+
+ReactDOM.render(e('div', null, 'Hello World'),


fb style. (I think this example might also be clearer if it defined a class since ReactDOM.render is comparatively rare.)

lacker and others added 10 commits October 4, 2016 12:02

get started on jsx

e749787

Fix the conflict

a2360a9

Merge branch 'new-docs' into jsx

62d191f

change title to make downloading easier

4db536b

react without jsx

5affefc

be nicer to JSX haters

5c5848a

another chunk of docs

5a51296

jsx in depth, last bit

e0b8c22

roll some tips into the JSX section

fcc1572

fix some subtitles

f3be937

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

gaearon requested changes Oct 5, 2016

View reviewed changes

lacker added 3 commits October 5, 2016 10:19

id -> classname

378a413

dont say jsx element

22d8b0e

mention script tags add a react global

b3f032f

lacker added 6 commits October 5, 2016 10:23

cut down to one dot-example

17f9621

make the first section name clearer

1be287d

always name functions

3e2c5c2

re-describe the lowercase letters

81b2430

remove accidental braces

989d0db

move MyComponent into fn

7823396

keyz reviewed Oct 5, 2016

View reviewed changes

lacker added 2 commits October 5, 2016 10:39

add keys for list example

7dd40f6

describe whitespace

2ac4495

keyz reviewed Oct 5, 2016

View reviewed changes

sophiebits reviewed Oct 5, 2016

View reviewed changes

lacker added 3 commits October 5, 2016 13:21

use normaler jsx

db2b6ee

Take bens wording

b278558

update the expression-as-element-type example

a3cc80e

gaearon reviewed Oct 5, 2016

View reviewed changes

lacker added 16 commits October 5, 2016 13:33

make each if branch make a component

25ca2cb

update explanation of whitespace rules

6ab8ec2

tweak

edd20c2

fix children-callback example

654117e

add example for rendering {false}

d46ac2d

fix some styling

3a54cb6

make it clear that we are talking about compiling

81172b3

change explanation of true shorthand discouragement

398ca23

alter title

4e4685f

children -> ...children

aa5c9ad

realistify example code

2025822

invoke -> use

66fb7c3

dont export

4595438

bit more explanation

3f5e478

add some dan text

e87bccc

Item instead of fn

ffb4241

vjeux reviewed Oct 5, 2016

View reviewed changes

lacker added 2 commits October 5, 2016 14:33

style tweaks

ebb3567

Merge branch 'new-docs' of https://github.com/facebook/react into jsx

bd49d93

lacker merged commit a73c770 into facebook:new-docs Oct 5, 2016

lacker deleted the jsx branch October 5, 2016 21:46

sophiebits reviewed Oct 5, 2016

View reviewed changes

gaearon mentioned this pull request Oct 6, 2016

Documentation inconsistencies around Parent/Child vs Owner/Ownee #7794

Closed

nylen mentioned this pull request Feb 14, 2017

Bring back the "JSX Gotchas" doc #8998

Closed


		## HTML Tags and React Components

		The first part of a JSX tag determines the type of the JSX element.


		A React component can't return multiple JSX elements, but a single JSX element can have multiple children, so if you want a component to render multiple things you can wrap it in a `div` like this.

		When you pass JSX as the children, `props.children` does not actually let you access the child component from the parent. Instead, it lets you access the return value of `React.createElement` calls using the `React.Children` helper library. Generally, accessing children in this way is only useful to return in a render function, rather than modifying or altering the children.


		This usage is not common, but it works if you want to stretch what JSX is capable of.

		`false` or `null` are valid children. They simply don't render. These JSX expressions will all render to the same thing:


		If you don't use a JavaScript bundler and added React as a script tag, it is already in scope as a React global.

		You can also refer to a React component using dot-notation from within JSX. This is convenient if you have a single module that exports many React components. For example, if `MyComponents.DatePicker` is a component, you can invoke it directly from JSX with:


		<div>{false}</div>

		<div>{null}</div>

JSX Docs: JSX In Depth and React Without JSX #7878

JSX Docs: JSX In Depth and React Without JSX #7878

Uh oh!

Conversation

lacker commented Oct 5, 2016

Uh oh!

lacker commented Oct 5, 2016

Uh oh!

lacker commented Oct 5, 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!

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!

sophiebits commented Oct 5, 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!