Document justification for dangerouslySetInnerHTML, fixes #2256
Conflicts: docs/_data/nav_tips.yml docs/tips/17-children-undefined.md
Jim committed
Jan 20, 2015 at 12:09 UTC
6f44f6049edfd7a66448ac50cd4415f6c26fd4b5
6 files changed
+30
-3
docs/_data/nav_tips.yml
+2
@@ -36,3 +36,5 @@
36
title: this.props.children undefined
37
- id: use-react-with-other-libraries
38
title: Use React with Other Libraries
39
+ - id: dangerously-set-inner-html
40
+ title: Dangerously Set innerHTML
docs/docs/02.3-jsx-gotchas.md
+1
-1
@@ -46,7 +46,7 @@ You can use mixed arrays with strings and JSX elements.
46
<div>{['First ', <span>·</span>, ' Second']}</div>
47
```
48
49
-As a last resort, you always have the ability to insert raw HTML.
49
+As a last resort, you always have the ability to [insert raw HTML](/react/docs/dom-differences.html).
50
51
```javascript
52
<div dangerouslySetInnerHTML={{'{{'}}__html: 'First · Second'}} />
docs/docs/ref-07-special-non-dom-attributes.md
+1
-1
@@ -10,4 +10,4 @@ Beside [DOM differences](/react/docs/dom-differences.html), React offers some at
10
11
- `key`: an optional, unique identifier. When your component shuffles around during `render` passes, it might be destroyed and recreated due to the diff algorithm. Assigning it a key that persists makes sure the component stays. See more [here](/react/docs/multiple-components.html#dynamic-children).
12
- `ref`: see [here](/react/docs/more-about-refs.html).
13
-- `dangerouslySetInnerHTML`: takes an object with the key `__html` and a DOM string as value. This is mainly for cooperating with DOM string manipulation libraries. Refer to the last example on the front page.
13
+- `dangerouslySetInnerHTML`: Provides the ability to insert raw HTML, mainly for cooperating with DOM string manipulation libraries. See more [here](/react/tips/dangerously-set-inner-html.html).
docs/tips/17-children-undefined.md
+1
-1
@@ -25,4 +25,4 @@ var App = React.createClass({
25
React.render(<App></App>, mountNode);
26
```
27
28
-To access your own subcomponents (the `span`s), place [refs](http://facebook.github.io/react/docs/more-about-refs.html) on them.
28
+For a more sophisticated example, refer to the last example on the [front page](/).
docs/tips/18-use-react-with-other-libraries.md
+1
@@ -4,6 +4,7 @@ title: Use React with Other Libraries
4
layout: tips
5
permalink: use-react-with-other-libraries.html
6
prev: children-undefined.html
7
+next: dangerously-set-inner-html.html
8
---
9
10
You don't have to go full React. The component [lifecycle events](/react/docs/component-specs.html#lifecycle-methods), especially `componentDidMount` and `componentDidUpdate`, are good places to put your other libraries' logic.
docs/tips/19--dangerouslySetInnerHTML.md
new
+24
@@ -0,0 +1,24 @@
1
+---
2
+id: dangerously-set-inner-html
3
+title: Dangerously Set innerHTML
4
+layout: tips
5
+permalink: dangerously-set-inner-html.html
6
+prev: children-undefined.html
7
+---
8
+
9
+Improper use of the `innerHTML` can open you up to a [cross-site scripting (XSS)](http://en.wikipedia.org/wiki/Cross-site_scripting) attack. Sanitizing user input for display is notoriously error-prone, and failure to properly sanitize is one of the [leading causes of web vulnerabilities](http://owasptop10.googlecode.com/files/OWASP%20Top%2010%20-%202013.pdf) on the internet.
10
+
11
+Our design philosophy is that it should be “easy” to make things safe, and developers should explicitly state their intent when performing “unsafe” operations. The prop name `dangerouslySetInnerHTML` is intentionally chosen to be frightening, and the prop value (an object instead of a string) can be used to indicate sanitized data.
12
+
13
+After fully understanding the security ramifications and properly sanitizing the data, create a new object containing only the key `__html` and your sanitized data as the value. Here is an example using the JSX syntax:
14
+
15
+```js
16
+function createMarkup() { return {__html: 'First · Second'}; };
17
+<div dangerouslySetInnerHTML={createMarkup()} />
18
+```
19
+
20
+The point being that if you unintentionally do say `<div dangerouslySetInnerHTML={getUsername()} />` it will not be rendered because `getUsername()` would return a plain `string` and not a `{__html: ''}` object. The intent behind the `{__html:...}` syntax is that it be considered a "type/taint" of sorts. Sanitized data can be returned from a function using this wrapper object, and this marked data can subsequently be passed into `dangerouslySetInnerHTML`. For this reason, we recommend against writing code of the form `<div dangerouslySetInnerHTML={{'{{'}}__html: getMarkup()}} />`.
21
+
22
+This functionality is mainly provided for cooperation with DOM string manipulation libraries, so the HTML provided must be well-formed (ie., pass XML validation).
23
+
24
+For a more complete usage example, refer to the last example on the [front page](/).