The library for web and native user interfaces.
Adding JSX pitfalls section in the docs
Vjeux committed
Jun 13, 2013 at 01:00 UTC
d7a5f137ffdbb1e704c7d0d1108cc4bf09f0a4e2
3 files changed
+103
docs/_includes/nav_docs.html
+7
@@ -21,4 +21,11 @@
21
<li><a href="/react/docs/api.html"{% if page.id == 'docs-api' %} class="active"{% endif %}>API</a></li>
22
</ul>
23
</div>
24
+
25
+ <div class="nav-docs-section">
26
+ <h3>Appendix</h3>
27
+ <ul>
28
+ <li><a href="/react/docs/jsx-is-not-html.html"{% if page.id == 'docs-jsx-is-not-html' %} class="active"{% endif %}>JSX is not HTML</a></li>
29
+ </ul>
30
+ </div>
31
</div>
docs/docs/api.md
+1
@@ -3,6 +3,7 @@ id: docs-api
3
title: React API
4
layout: docs
5
prev: mixins.html
6
+next: jsx-is-not-html.html
7
---
8
9
## React
docs/docs/jsx-is-not-html.md
new
+95
@@ -0,0 +1,95 @@
1
+---
2
+id: docs-jsx-is-not-html
3
+title: JSX is not HTML
4
+description: Differences between JSX and HTML.
5
+layout: docs
6
+prev: api.html
7
+---
8
+
9
+JSX looks like HTML but there are some important differences you may run into.
10
+
11
+## Whitespace removal
12
+
13
+JSX doesn't follow the same whitespace elimination rules as HTML. JSX removes all the whitespaces between two curly braces expressions. If you want to have a white space, a work-around is to add `{' '}`.
14
+
15
+```javascript
16
+<div>{this.props.name} {' '} {this.props.surname}</div>
17
+```
18
+
19
+This behavior is still being debated. Follow [Issue #65](https://github.com/facebook/react/issues/65) to be updated on the situation.
20
+
21
+## HTML Entities
22
+
23
+You can insert HTML entities within literal text in JSX:
24
+
25
+```javascript
26
+<div>First · Second</div>
27
+```
28
+
29
+If you want to display an HTML entity within a dynamic content, you will run into double escaping issues as React escapes all the strings you are displaying in order to prevent a wide range of XSS attacks by default.
30
+
31
+```javascript
32
+// Bad: It displays "First · Second"
33
+<div>{'First · Second'}</div>
34
+```
35
+
36
+There are various ways to work-around this issue. The easiest one is to write unicode character directly in Javascript. You've got to make sure that the file is saved as UTF-8 and that the propers UTF-8 directives are set so the browser will display it correctly.
37
+
38
+```javascript
39
+<div>{'First · Second'}</div>
40
+```
41
+
42
+A safer alternative is to find the <a href="http://www.fileformat.info/info/unicode/char/b7/index.htm">unicode number corresponding to the entity</a> and use it inside of a Javascript string.
43
+
44
+```javascript
45
+<div>{'First \u00b7 Second'}</div>
46
+<div>{'First ' + String.fromCharCode(183) + ' Second'}</div>
47
+```
48
+
49
+You can use mixed arrays with strings and JSX elements.
50
+
51
+```javascript
52
+<div>{['First ', <span>·</span>, ' Second']}</div>
53
+```
54
+
55
+In last resort, you always have the ability to insert raw HTML inside of the div.
56
+
57
+```javascript
58
+<div dangerouslySetInnerHTML={{'{{'}}__html: 'First · Second'}} />
59
+```
60
+
61
+## Comments
62
+
63
+JSX supports both single-line and multi-lines Javascript comments within a tag declaration:
64
+
65
+```javascript
66
+<div // This is a single line comment:
67
+ /*
68
+ And a multiline
69
+ comment
70
+ */
71
+/>
72
+```
73
+
74
+As of React 0.3, there is no good way to insert comments within the children section. [Issue #82](https://github.com/facebook/react/issues/82) is tracking progress to enable the following way to write comments:
75
+
76
+```javascript
77
+// Note: The following is not implemented yet!
78
+<div>
79
+ {/* This is a comment */}
80
+</div>
81
+```
82
+
83
+## Custom HTML attributes
84
+
85
+If you pass properties to native HTML elements that do not exist in the HTML specification, React will not render them. If you want to use a custom attribute, you should prefix it with `data-`.
86
+
87
+```javascript
88
+<div data-custom-attribute="foo" />
89
+```
90
+
91
+[Web Accessibility](http://www.w3.org/WAI/intro/aria) attributes starting with `aria-` will be rendered properly.
92
+
93
+```javascript
94
+<div aria-hidden={true} />
95
+```