Facebook/react
1
0
Fork 0
mirror of https://github.com/facebook/react.git synced 2025-11-01 09:12:30 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
a0924bb67a4847cd52be2dbe8d28fe7fb512fd69
react/docs/jsx-in-depth.html
T
Circle CI a0924bb67a Rebuild website
2017-02-02 05:33:01 -08:00

697 lines
50 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>JSX In Depth - React</title>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta property="og:title" content="JSX In Depth - React">
<meta property="og:type" content="website">
<meta property="og:url" content="https://facebook.github.io/react/docs/jsx-in-depth.html">
<meta property="og:image" content="https://facebook.github.io/react/img/logo_og.png">
<meta property="og:description" content="A JavaScript library for building user interfaces">
<meta property="fb:app_id" content="623268441017527">
<link rel="shortcut icon" href="/react/favicon.ico">
<link rel="alternate" type="application/rss+xml" title="React" href="https://facebook.github.io/react/feed.xml">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css" />
<link rel="stylesheet" href="/react/css/syntax.css">
<link rel="stylesheet" href="/react/css/codemirror.css">
<link rel="stylesheet" href="/react/css/react.css">
<script src="//use.typekit.net/vqa1hcx.js"></script>
<script>try{Typekit.load();}catch(e){}</script>
<!--[if lte IE 8]>
<script src="/react/js/html5shiv.min.js"></script>
<script src="/react/js/es5-shim.min.js"></script>
<script src="/react/js/es5-sham.min.js"></script>
<![endif]-->
<script type="text/javascript" src="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.js"></script>
<script src="/react/js/codemirror.js"></script>
<script src="/react/js/javascript.js"></script>
<script src="/react/js/xml.js"></script>
<script src="/react/js/jsx.js"></script>
<script src="/react/js/react.js"></script>
<script src="/react/js/react-dom.js"></script>
<script src="/react/js/babel.min.js"></script>
<script src="/react/js/live_editor.js"></script>
</head>
<body>
<div class="container">
<div class="nav-main">
<div class="wrap">
<a class="nav-home" href="/react/">
<img class="nav-logo" src="/react/img/logo.svg" width="36" height="36">
React
</a>
<div class="nav-lists">
<ul class="nav-site nav-site-internal">
<li><a href="/react/docs/hello-world.html" class="active">Docs</a></li>
<li><a href="/react/tutorial/tutorial.html">Tutorial</a></li>
<li><a href="/react/community/support.html">Community</a></li>
<li><a href="/react/blog/">Blog</a></li>
<li class="nav-site-search">
<input id="algolia-doc-search" type="text" placeholder="Search docs..." />
</li>
</ul>
<ul class="nav-site nav-site-external">
<li><a href="https://github.com/facebook/react">GitHub</a></li>
<li><a href="https://github.com/facebook/react/releases">v15.4.2</a></li>
</ul>
</div>
</div>
</div>
<section class="content wrap documentationContent">
<div class="inner-content">
<a class="edit-page-link" href="https://github.com/facebook/react/tree/master/docs/docs/jsx-in-depth.md" target="_blank">Edit on GitHub</a>
<h1>
JSX In Depth
</h1>
<div class="subHeader"></div>
<p>Fundamentally, JSX just provides syntactic sugar for the <code>React.createElement(component, props, ...children)</code> function. The JSX code:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">MyButton</span> <span class="nx">color</span><span class="o">=</span><span class="s2">&quot;blue&quot;</span> <span class="nx">shadowSize</span><span class="o">=</span><span class="p">{</span><span class="mi">2</span><span class="p">}</span><span class="o">&gt;</span>
<span class="nx">Click</span> <span class="nx">Me</span>
<span class="o">&lt;</span><span class="err">/MyButton&gt;</span>
</code></pre></div>
<p>compiles into:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">React</span><span class="p">.</span><span class="nx">createElement</span><span class="p">(</span>
<span class="nx">MyButton</span><span class="p">,</span>
<span class="p">{</span><span class="nx">color</span><span class="o">:</span> <span class="s1">&#39;blue&#39;</span><span class="p">,</span> <span class="nx">shadowSize</span><span class="o">:</span> <span class="mi">2</span><span class="p">},</span>
<span class="s1">&#39;Click Me&#39;</span>
<span class="p">)</span>
</code></pre></div>
<p>You can also use the self-closing form of the tag if there are no children. So:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">div</span> <span class="nx">className</span><span class="o">=</span><span class="s2">&quot;sidebar&quot;</span> <span class="o">/&gt;</span>
</code></pre></div>
<p>compiles into:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="nx">React</span><span class="p">.</span><span class="nx">createElement</span><span class="p">(</span>
<span class="s1">&#39;div&#39;</span><span class="p">,</span>
<span class="p">{</span><span class="nx">className</span><span class="o">:</span> <span class="s1">&#39;sidebar&#39;</span><span class="p">},</span>
<span class="kc">null</span>
<span class="p">)</span>
</code></pre></div>
<p>If you want to test out how some specific JSX is converted into JavaScript, you can try out <a href="https://babeljs.io/repl/#?babili=false&amp;evaluate=true&amp;lineWrap=false&amp;presets=es2015%2Creact%2Cstage-0&amp;code=function%20hello()%20%7B%0A%20%20return%20%3Cdiv%3EHello%20world!%3C%2Fdiv%3E%3B%0A%7D">the online Babel compiler</a>.</p>
<h2><a class="anchor" name="specifying-the-react-element-type"></a>Specifying The React Element Type <a class="hash-link" href="#specifying-the-react-element-type">#</a></h2>
<p>The first part of a JSX tag determines the type of the React element.</p>
<p>Capitalized types indicate that the JSX tag is referring to a React component. These tags get compiled into a direct reference to the named variable, so if you use the JSX <code>&lt;Foo /&gt;</code> expression, <code>Foo</code> must be in scope.</p>
<h3><a class="anchor" name="react-must-be-in-scope"></a>React Must Be in Scope <a class="hash-link" href="#react-must-be-in-scope">#</a></h3>
<p>Since JSX compiles into calls to <code>React.createElement</code>, the <code>React</code> library must also always be in scope from your JSX code.</p>
<p>For example, both of the imports are necessary in this code, even though <code>React</code> and <code>CustomButton</code> are not directly referenced from JavaScript:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="hll"><span class="kr">import</span> <span class="nx">React</span> <span class="nx">from</span> <span class="s1">&#39;react&#39;</span><span class="p">;</span>
</span><span class="hll"><span class="kr">import</span> <span class="nx">CustomButton</span> <span class="nx">from</span> <span class="s1">&#39;./CustomButton&#39;</span><span class="p">;</span>
</span>
<span class="kd">function</span> <span class="nx">WarningButton</span><span class="p">()</span> <span class="p">{</span>
<span class="hll"> <span class="c1">// return React.createElement(CustomButton, {color: &#39;red&#39;}, null);</span>
</span> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">CustomButton</span> <span class="nx">color</span><span class="o">=</span><span class="s2">&quot;red&quot;</span> <span class="o">/&gt;</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div>
<p>If you don&#39;t use a JavaScript bundler and added React as a script tag, it is already in scope as a <code>React</code> global.</p>
<h3><a class="anchor" name="using-dot-notation-for-jsx-type"></a>Using Dot Notation for JSX Type <a class="hash-link" href="#using-dot-notation-for-jsx-type">#</a></h3>
<p>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 <code>MyComponents.DatePicker</code> is a component, you can use it directly from JSX with:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kr">import</span> <span class="nx">React</span> <span class="nx">from</span> <span class="s1">&#39;react&#39;</span><span class="p">;</span>
<span class="kr">const</span> <span class="nx">MyComponents</span> <span class="o">=</span> <span class="p">{</span>
<span class="nx">DatePicker</span><span class="o">:</span> <span class="kd">function</span> <span class="nx">DatePicker</span><span class="p">(</span><span class="nx">props</span><span class="p">)</span> <span class="p">{</span>
<span class="k">return</span> <span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="nx">Imagine</span> <span class="nx">a</span> <span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">color</span><span class="p">}</span> <span class="nx">datepicker</span> <span class="nx">here</span><span class="p">.</span><span class="o">&lt;</span><span class="err">/div&gt;;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nx">BlueDatePicker</span><span class="p">()</span> <span class="p">{</span>
<span class="hll"> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">MyComponents</span><span class="p">.</span><span class="nx">DatePicker</span> <span class="nx">color</span><span class="o">=</span><span class="s2">&quot;blue&quot;</span> <span class="o">/&gt;</span><span class="p">;</span>
</span><span class="p">}</span>
</code></pre></div><h3><a class="anchor" name="user-defined-components-must-be-capitalized"></a>User-Defined Components Must Be Capitalized <a class="hash-link" href="#user-defined-components-must-be-capitalized">#</a></h3>
<p>When an element type starts with a lowercase letter, it refers to a built-in component like <code>&lt;div&gt;</code> or <code>&lt;span&gt;</code> and results in a string <code>&#39;div&#39;</code> or <code>&#39;span&#39;</code> passed to <code>React.createElement</code>. Types that start with a capital letter like <code>&lt;Foo /&gt;</code> compile to <code>React.createElement(Foo)</code> and correspond to a component defined or imported in your JavaScript file.</p>
<p>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.</p>
<p>For example, this code will not run as expected:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kr">import</span> <span class="nx">React</span> <span class="nx">from</span> <span class="s1">&#39;react&#39;</span><span class="p">;</span>
<span class="hll"><span class="c1">// Wrong! This is a component and should have been capitalized:</span>
</span><span class="hll"><span class="kd">function</span> <span class="nx">hello</span><span class="p">(</span><span class="nx">props</span><span class="p">)</span> <span class="p">{</span>
</span> <span class="c1">// Correct! This use of &lt;div&gt; is legitimate because div is a valid HTML tag:</span>
<span class="k">return</span> <span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="nx">Hello</span> <span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">toWhat</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/div&gt;;</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nx">HelloWorld</span><span class="p">()</span> <span class="p">{</span>
<span class="hll"> <span class="c1">// Wrong! React thinks &lt;hello /&gt; is an HTML tag because it&#39;s not capitalized:</span>
</span><span class="hll"> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">hello</span> <span class="nx">toWhat</span><span class="o">=</span><span class="s2">&quot;World&quot;</span> <span class="o">/&gt;</span><span class="p">;</span>
</span><span class="p">}</span>
</code></pre></div>
<p>To fix this, we will rename <code>hello</code> to <code>Hello</code> and use <code>&lt;Hello /&gt;</code> when referring to it:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kr">import</span> <span class="nx">React</span> <span class="nx">from</span> <span class="s1">&#39;react&#39;</span><span class="p">;</span>
<span class="hll"><span class="c1">// Correct! This is a component and should be capitalized:</span>
</span><span class="hll"><span class="kd">function</span> <span class="nx">Hello</span><span class="p">(</span><span class="nx">props</span><span class="p">)</span> <span class="p">{</span>
</span> <span class="c1">// Correct! This use of &lt;div&gt; is legitimate because div is a valid HTML tag:</span>
<span class="k">return</span> <span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="nx">Hello</span> <span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">toWhat</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/div&gt;;</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nx">HelloWorld</span><span class="p">()</span> <span class="p">{</span>
<span class="hll"> <span class="c1">// Correct! React knows &lt;Hello /&gt; is a component because it&#39;s capitalized.</span>
</span><span class="hll"> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">Hello</span> <span class="nx">toWhat</span><span class="o">=</span><span class="s2">&quot;World&quot;</span> <span class="o">/&gt;</span><span class="p">;</span>
</span><span class="p">}</span>
</code></pre></div><h3><a class="anchor" name="choosing-the-type-at-runtime"></a>Choosing the Type at Runtime <a class="hash-link" href="#choosing-the-type-at-runtime">#</a></h3>
<p>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. This often comes up when you want to render a different component based on a prop:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kr">import</span> <span class="nx">React</span> <span class="nx">from</span> <span class="s1">&#39;react&#39;</span><span class="p">;</span>
<span class="kr">import</span> <span class="p">{</span> <span class="nx">PhotoStory</span><span class="p">,</span> <span class="nx">VideoStory</span> <span class="p">}</span> <span class="nx">from</span> <span class="s1">&#39;./stories&#39;</span><span class="p">;</span>
<span class="kr">const</span> <span class="nx">components</span> <span class="o">=</span> <span class="p">{</span>
<span class="nx">photo</span><span class="o">:</span> <span class="nx">PhotoStory</span><span class="p">,</span>
<span class="nx">video</span><span class="o">:</span> <span class="nx">VideoStory</span>
<span class="p">};</span>
<span class="kd">function</span> <span class="nx">Story</span><span class="p">(</span><span class="nx">props</span><span class="p">)</span> <span class="p">{</span>
<span class="hll"> <span class="c1">// Wrong! JSX type can&#39;t be an expression.</span>
</span><span class="hll"> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">components</span><span class="p">[</span><span class="nx">props</span><span class="p">.</span><span class="nx">storyType</span><span class="p">]</span> <span class="nx">story</span><span class="o">=</span><span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">story</span><span class="p">}</span> <span class="o">/&gt;</span><span class="p">;</span>
</span><span class="p">}</span>
</code></pre></div>
<p>To fix this, we will assign the type to a capitalized variable first:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kr">import</span> <span class="nx">React</span> <span class="nx">from</span> <span class="s1">&#39;react&#39;</span><span class="p">;</span>
<span class="kr">import</span> <span class="p">{</span> <span class="nx">PhotoStory</span><span class="p">,</span> <span class="nx">VideoStory</span> <span class="p">}</span> <span class="nx">from</span> <span class="s1">&#39;./stories&#39;</span><span class="p">;</span>
<span class="kr">const</span> <span class="nx">components</span> <span class="o">=</span> <span class="p">{</span>
<span class="nx">photo</span><span class="o">:</span> <span class="nx">PhotoStory</span><span class="p">,</span>
<span class="nx">video</span><span class="o">:</span> <span class="nx">VideoStory</span>
<span class="p">};</span>
<span class="hll"><span class="kd">function</span> <span class="nx">Story</span><span class="p">(</span><span class="nx">props</span><span class="p">)</span> <span class="p">{</span>
</span><span class="hll"> <span class="c1">// Correct! JSX type can be a capitalized variable.</span>
</span><span class="hll"> <span class="kr">const</span> <span class="nx">SpecificStory</span> <span class="o">=</span> <span class="nx">components</span><span class="p">[</span><span class="nx">props</span><span class="p">.</span><span class="nx">storyType</span><span class="p">];</span>
</span> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">SpecificStory</span> <span class="nx">story</span><span class="o">=</span><span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">story</span><span class="p">}</span> <span class="o">/&gt;</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div><h2><a class="anchor" name="props-in-jsx"></a>Props in JSX <a class="hash-link" href="#props-in-jsx">#</a></h2>
<p>There are several different ways to specify props in JSX.</p>
<h3><a class="anchor" name="javascript-expressions"></a>JavaScript Expressions <a class="hash-link" href="#javascript-expressions">#</a></h3>
<p>You can pass any JavaScript expression as a prop, by surrounding it with <code>{}</code>. For example, in this JSX:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">MyComponent</span> <span class="nx">foo</span><span class="o">=</span><span class="p">{</span><span class="mi">1</span> <span class="o">+</span> <span class="mi">2</span> <span class="o">+</span> <span class="mi">3</span> <span class="o">+</span> <span class="mi">4</span><span class="p">}</span> <span class="o">/&gt;</span>
</code></pre></div>
<p>For <code>MyComponent</code>, the value of <code>props.foo</code> will be <code>10</code> because the expression <code>1 + 2 + 3 + 4</code> gets evaluated.</p>
<p><code>if</code> statements and <code>for</code> loops are not expressions in JavaScript, so they can&#39;t be used in JSX directly. Instead, you can put these in the surrounding code. For example:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">NumberDescriber</span><span class="p">(</span><span class="nx">props</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">let</span> <span class="nx">description</span><span class="p">;</span>
<span class="hll"> <span class="k">if</span> <span class="p">(</span><span class="nx">props</span><span class="p">.</span><span class="nx">number</span> <span class="o">%</span> <span class="mi">2</span> <span class="o">==</span> <span class="mi">0</span><span class="p">)</span> <span class="p">{</span>
</span><span class="hll"> <span class="nx">description</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">strong</span><span class="o">&gt;</span><span class="nx">even</span><span class="o">&lt;</span><span class="err">/strong&gt;;</span>
</span><span class="hll"> <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
</span><span class="hll"> <span class="nx">description</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">i</span><span class="o">&gt;</span><span class="nx">odd</span><span class="o">&lt;</span><span class="err">/i&gt;;</span>
</span><span class="hll"> <span class="p">}</span>
</span> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">number</span><span class="p">}</span> <span class="nx">is</span> <span class="nx">an</span> <span class="p">{</span><span class="nx">description</span><span class="p">}</span> <span class="nx">number</span><span class="o">&lt;</span><span class="err">/div&gt;;</span>
<span class="p">}</span>
</code></pre></div><h3><a class="anchor" name="string-literals"></a>String Literals <a class="hash-link" href="#string-literals">#</a></h3>
<p>You can pass a string literal as a prop. These two JSX expressions are equivalent:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">MyComponent</span> <span class="nx">message</span><span class="o">=</span><span class="s2">&quot;hello world&quot;</span> <span class="o">/&gt;</span>
<span class="o">&lt;</span><span class="nx">MyComponent</span> <span class="nx">message</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;hello world&#39;</span><span class="p">}</span> <span class="o">/&gt;</span>
</code></pre></div>
<p>When you pass a string literal, its value is HTML-unescaped. So these two JSX expressions are equivalent:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">MyComponent</span> <span class="nx">message</span><span class="o">=</span><span class="s2">&quot;&amp;lt;3&quot;</span> <span class="o">/&gt;</span>
<span class="o">&lt;</span><span class="nx">MyComponent</span> <span class="nx">message</span><span class="o">=</span><span class="p">{</span><span class="s1">&#39;&lt;3&#39;</span><span class="p">}</span> <span class="o">/&gt;</span>
</code></pre></div>
<p>This behavior is usually not relevant. It&#39;s only mentioned here for completeness.</p>
<h3><a class="anchor" name="props-default-to-true"></a>Props Default to &quot;True&quot; <a class="hash-link" href="#props-default-to-true">#</a></h3>
<p>If you pass no value for a prop, it defaults to <code>true</code>. These two JSX expressions are equivalent:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">MyTextBox</span> <span class="nx">autocomplete</span> <span class="o">/&gt;</span>
<span class="o">&lt;</span><span class="nx">MyTextBox</span> <span class="nx">autocomplete</span><span class="o">=</span><span class="p">{</span><span class="kc">true</span><span class="p">}</span> <span class="o">/&gt;</span>
</code></pre></div>
<p>In general, we don&#39;t recommend using this because it can be confused with the <a href="https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Operators/Object_initializer#New_notations_in_ECMAScript_2015">ES6 object shorthand</a> <code>{foo}</code> which is short for <code>{foo: foo}</code> rather than <code>{foo: true}</code>. This behavior is just there so that it matches the behavior of HTML.</p>
<h3><a class="anchor" name="spread-attributes"></a>Spread Attributes <a class="hash-link" href="#spread-attributes">#</a></h3>
<p>If you already have <code>props</code> as an object, and you want to pass it in JSX, you can use <code>...</code> as a &quot;spread&quot; operator to pass the whole props object. These two components are equivalent:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">App1</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="o">&lt;</span><span class="nx">Greeting</span> <span class="nx">firstName</span><span class="o">=</span><span class="s2">&quot;Ben&quot;</span> <span class="nx">lastName</span><span class="o">=</span><span class="s2">&quot;Hector&quot;</span> <span class="o">/&gt;</span><span class="p">;</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nx">App2</span><span class="p">()</span> <span class="p">{</span>
<span class="kr">const</span> <span class="nx">props</span> <span class="o">=</span> <span class="p">{</span><span class="nx">firstName</span><span class="o">:</span> <span class="s1">&#39;Ben&#39;</span><span class="p">,</span> <span class="nx">lastName</span><span class="o">:</span> <span class="s1">&#39;Hector&#39;</span><span class="p">};</span>
<span class="hll"> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">Greeting</span> <span class="p">{...</span><span class="nx">props</span><span class="p">}</span> <span class="o">/&gt;</span><span class="p">;</span>
</span><span class="p">}</span>
</code></pre></div>
<p>Spread attributes can be useful when you are building generic containers. However, they can also make your code messy by making it easy to pass a lot of irrelevant props to components that don&#39;t care about them. We recommend that you use this syntax sparingly.</p>
<h2><a class="anchor" name="children-in-jsx"></a>Children in JSX <a class="hash-link" href="#children-in-jsx">#</a></h2>
<p>In JSX expressions that contain both an opening tag and a closing tag, the content between those tags is passed as a special prop: <code>props.children</code>. There are several different ways to pass children:</p>
<h3><a class="anchor" name="string-literals"></a>String Literals <a class="hash-link" href="#string-literals">#</a></h3>
<p>You can put a string between the opening and closing tags and <code>props.children</code> will just be that string. This is useful for many of the built-in HTML elements. For example:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">MyComponent</span><span class="o">&gt;</span><span class="nx">Hello</span> <span class="nx">world</span><span class="o">!&lt;</span><span class="err">/MyComponent&gt;</span>
</code></pre></div>
<p>This is valid JSX, and <code>props.children</code> in <code>MyComponent</code> will simply be the string <code>&quot;Hello world!&quot;</code>. HTML is unescaped, so you can generally write JSX just like you would write HTML in this way:</p>
<div class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;div&gt;</span>This is valid HTML <span class="ni">&amp;amp;</span> JSX at the same time.<span class="nt">&lt;/div&gt;</span>
</code></pre></div>
<p>JSX removes whitespace at the beginning and ending of a line. It also removes blank lines. New lines adjacent to tags are removed; new lines that occur in the middle of string literals are condensed into a single space. So these all render to the same thing:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="nx">Hello</span> <span class="nx">World</span><span class="o">&lt;</span><span class="err">/div&gt;</span>
<span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span>
<span class="nx">Hello</span> <span class="nx">World</span>
<span class="o">&lt;</span><span class="err">/div&gt;</span>
<span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span>
<span class="nx">Hello</span>
<span class="nx">World</span>
<span class="o">&lt;</span><span class="err">/div&gt;</span>
<span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span>
<span class="nx">Hello</span> <span class="nx">World</span>
<span class="o">&lt;</span><span class="err">/div&gt;</span>
</code></pre></div><h3><a class="anchor" name="jsx-children"></a>JSX Children <a class="hash-link" href="#jsx-children">#</a></h3>
<p>You can provide more JSX elements as the children. This is useful for displaying nested components:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">MyContainer</span><span class="o">&gt;</span>
<span class="o">&lt;</span><span class="nx">MyFirstComponent</span> <span class="o">/&gt;</span>
<span class="o">&lt;</span><span class="nx">MySecondComponent</span> <span class="o">/&gt;</span>
<span class="o">&lt;</span><span class="err">/MyContainer&gt;</span>
</code></pre></div>
<p>You can mix together different types of children, so you can use string literals together with JSX children. This is another way in which JSX is like HTML, so that this is both valid JSX and valid HTML:</p>
<div class="highlight"><pre><code class="language-html" data-lang="html"><span class="nt">&lt;div&gt;</span>
Here is a list:
<span class="nt">&lt;ul&gt;</span>
<span class="nt">&lt;li&gt;</span>Item 1<span class="nt">&lt;/li&gt;</span>
<span class="nt">&lt;li&gt;</span>Item 2<span class="nt">&lt;/li&gt;</span>
<span class="nt">&lt;/ul&gt;</span>
<span class="nt">&lt;/div&gt;</span>
</code></pre></div>
<p>A React component can&#39;t return multiple React elements, but a single JSX expression can have multiple children, so if you want a component to render multiple things you can wrap it in a <code>div</code> like this.</p>
<h3><a class="anchor" name="javascript-expressions"></a>JavaScript Expressions <a class="hash-link" href="#javascript-expressions">#</a></h3>
<p>You can pass any JavaScript expression as children, by enclosing it within <code>{}</code>. For example, these expressions are equivalent:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">MyComponent</span><span class="o">&gt;</span><span class="nx">foo</span><span class="o">&lt;</span><span class="err">/MyComponent&gt;</span>
<span class="o">&lt;</span><span class="nx">MyComponent</span><span class="o">&gt;</span><span class="p">{</span><span class="s1">&#39;foo&#39;</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/MyComponent&gt;</span>
</code></pre></div>
<p>This is often useful for rendering a list of JSX expressions of arbitrary length. For example, this renders an HTML list:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">Item</span><span class="p">(</span><span class="nx">props</span><span class="p">)</span> <span class="p">{</span>
<span class="hll"> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">li</span><span class="o">&gt;</span><span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">message</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/li&gt;;</span>
</span><span class="p">}</span>
<span class="kd">function</span> <span class="nx">TodoList</span><span class="p">()</span> <span class="p">{</span>
<span class="kr">const</span> <span class="nx">todos</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;finish doc&#39;</span><span class="p">,</span> <span class="s1">&#39;submit pr&#39;</span><span class="p">,</span> <span class="s1">&#39;nag dan to review&#39;</span><span class="p">];</span>
<span class="k">return</span> <span class="p">(</span>
<span class="o">&lt;</span><span class="nx">ul</span><span class="o">&gt;</span>
<span class="hll"> <span class="p">{</span><span class="nx">todos</span><span class="p">.</span><span class="nx">map</span><span class="p">((</span><span class="nx">message</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="o">&lt;</span><span class="nx">Item</span> <span class="nx">key</span><span class="o">=</span><span class="p">{</span><span class="nx">message</span><span class="p">}</span> <span class="nx">message</span><span class="o">=</span><span class="p">{</span><span class="nx">message</span><span class="p">}</span> <span class="o">/&gt;</span><span class="p">)}</span>
</span> <span class="o">&lt;</span><span class="err">/ul&gt;</span>
<span class="p">);</span>
<span class="p">}</span>
</code></pre></div>
<p>JavaScript expressions can be mixed with other types of children. This is often useful in lieu of string templates:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="kd">function</span> <span class="nx">Hello</span><span class="p">(</span><span class="nx">props</span><span class="p">)</span> <span class="p">{</span>
<span class="hll"> <span class="k">return</span> <span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="nx">Hello</span> <span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">addressee</span><span class="p">}</span><span class="o">!&lt;</span><span class="err">/div&gt;;</span>
</span><span class="p">}</span>
</code></pre></div><h3><a class="anchor" name="functions-as-children"></a>Functions as Children <a class="hash-link" href="#functions-as-children">#</a></h3>
<p>Normally, JavaScript expressions inserted in JSX will evaluate to a string, a React element, or a list of those things. However, <code>props.children</code> works just like any other prop in that it can pass any sort of data, not just the sorts that React knows how to render. For example, if you have a custom component, you could have it take a callback as <code>props.children</code>:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="c1">// Calls the children callback numTimes to produce a repeated component</span>
<span class="kd">function</span> <span class="nx">Repeat</span><span class="p">(</span><span class="nx">props</span><span class="p">)</span> <span class="p">{</span>
<span class="kd">let</span> <span class="nx">items</span> <span class="o">=</span> <span class="p">[];</span>
<span class="hll"> <span class="k">for</span> <span class="p">(</span><span class="kd">let</span> <span class="nx">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="nx">i</span> <span class="o">&lt;</span> <span class="nx">props</span><span class="p">.</span><span class="nx">numTimes</span><span class="p">;</span> <span class="nx">i</span><span class="o">++</span><span class="p">)</span> <span class="p">{</span>
</span> <span class="nx">items</span><span class="p">.</span><span class="nx">push</span><span class="p">(</span><span class="nx">props</span><span class="p">.</span><span class="nx">children</span><span class="p">(</span><span class="nx">i</span><span class="p">));</span>
<span class="p">}</span>
<span class="k">return</span> <span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="p">{</span><span class="nx">items</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/div&gt;;</span>
<span class="p">}</span>
<span class="kd">function</span> <span class="nx">ListOfTenThings</span><span class="p">()</span> <span class="p">{</span>
<span class="k">return</span> <span class="p">(</span>
<span class="o">&lt;</span><span class="nx">Repeat</span> <span class="nx">numTimes</span><span class="o">=</span><span class="p">{</span><span class="mi">10</span><span class="p">}</span><span class="o">&gt;</span>
<span class="hll"> <span class="p">{(</span><span class="nx">index</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="o">&lt;</span><span class="nx">div</span> <span class="nx">key</span><span class="o">=</span><span class="p">{</span><span class="nx">index</span><span class="p">}</span><span class="o">&gt;</span><span class="nx">This</span> <span class="nx">is</span> <span class="nx">item</span> <span class="p">{</span><span class="nx">index</span><span class="p">}</span> <span class="k">in</span> <span class="nx">the</span> <span class="nx">list</span><span class="o">&lt;</span><span class="err">/div&gt;}</span>
</span> <span class="o">&lt;</span><span class="err">/Repeat&gt;</span>
<span class="p">);</span>
<span class="p">}</span>
</code></pre></div>
<p>Children passed to a custom component can be anything, as long as that component transforms them into something React can understand before rendering. This usage is not common, but it works if you want to stretch what JSX is capable of.</p>
<h3><a class="anchor" name="booleans-null-and-undefined-are-ignored"></a>Booleans, Null, and Undefined Are Ignored <a class="hash-link" href="#booleans-null-and-undefined-are-ignored">#</a></h3>
<p><code>false</code>, <code>null</code>, <code>undefined</code>, and <code>true</code> are valid children. They simply don&#39;t render. These JSX expressions will all render to the same thing:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">div</span> <span class="o">/&gt;</span>
<span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;&lt;</span><span class="err">/div&gt;</span>
<span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="p">{</span><span class="kc">false</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/div&gt;</span>
<span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="p">{</span><span class="kc">null</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/div&gt;</span>
<span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="p">{</span><span class="kc">undefined</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/div&gt;</span>
<span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span><span class="p">{</span><span class="kc">true</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/div&gt;</span>
</code></pre></div>
<p>This can be useful to conditionally render React elements. This JSX only renders a <code>&lt;Header /&gt;</code> if <code>showHeader</code> is <code>true</code>:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span>
<span class="hll"> <span class="p">{</span><span class="nx">showHeader</span> <span class="o">&amp;&amp;</span> <span class="o">&lt;</span><span class="nx">Header</span> <span class="o">/&gt;</span><span class="p">}</span>
</span> <span class="o">&lt;</span><span class="nx">Content</span> <span class="o">/&gt;</span>
<span class="o">&lt;</span><span class="err">/div&gt;</span>
</code></pre></div>
<p>One caveat is that some <a href="https://developer.mozilla.org/en-US/docs/Glossary/Falsy">&quot;falsy&quot; values</a>, such as the <code>0</code> number, are still rendered by React. For example, this code will not behave as you might expect because <code>0</code> will be printed when <code>props.messages</code> is an empty array:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span>
<span class="hll"> <span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">messages</span><span class="p">.</span><span class="nx">length</span> <span class="o">&amp;&amp;</span>
</span> <span class="o">&lt;</span><span class="nx">MessageList</span> <span class="nx">messages</span><span class="o">=</span><span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">messages</span><span class="p">}</span> <span class="o">/&gt;</span>
<span class="p">}</span>
<span class="o">&lt;</span><span class="err">/div&gt;</span>
</code></pre></div>
<p>To fix this, make sure that the expression before <code>&amp;&amp;</code> is always boolean:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span>
<span class="hll"> <span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">messages</span><span class="p">.</span><span class="nx">length</span> <span class="o">&gt;</span> <span class="mi">0</span> <span class="o">&amp;&amp;</span>
</span> <span class="o">&lt;</span><span class="nx">MessageList</span> <span class="nx">messages</span><span class="o">=</span><span class="p">{</span><span class="nx">props</span><span class="p">.</span><span class="nx">messages</span><span class="p">}</span> <span class="o">/&gt;</span>
<span class="p">}</span>
<span class="o">&lt;</span><span class="err">/div&gt;</span>
</code></pre></div>
<p>Conversely, if you want a value like <code>false</code>, <code>true</code>, <code>null</code>, or <code>undefined</code> to appear in the output, you have to <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String#String_conversion">convert it to a string</a> first:</p>
<div class="highlight"><pre><code class="language-js" data-lang="js"><span class="o">&lt;</span><span class="nx">div</span><span class="o">&gt;</span>
<span class="hll"> <span class="nx">My</span> <span class="nx">JavaScript</span> <span class="nx">variable</span> <span class="nx">is</span> <span class="p">{</span><span class="nb">String</span><span class="p">(</span><span class="nx">myVariable</span><span class="p">)}.</span>
</span><span class="o">&lt;</span><span class="err">/div&gt;</span>
</code></pre></div>
<div class="docs-prevnext">
</div>
</div>
<div class="nav-docs">
<!-- Docs Nav -->
<div class="nav-docs-section">
<h3>Quick Start</h3>
<ul>
<li>
<a href="/react/docs/installation.html">Installation</a>
</li>
<li>
<a href="/react/docs/hello-world.html">Hello World</a>
</li>
<li>
<a href="/react/docs/introducing-jsx.html">Introducing JSX</a>
</li>
<li>
<a href="/react/docs/rendering-elements.html">Rendering Elements</a>
</li>
<li>
<a href="/react/docs/components-and-props.html">Components and Props</a>
</li>
<li>
<a href="/react/docs/state-and-lifecycle.html">State and Lifecycle</a>
</li>
<li>
<a href="/react/docs/handling-events.html">Handling Events</a>
</li>
<li>
<a href="/react/docs/conditional-rendering.html">Conditional Rendering</a>
</li>
<li>
<a href="/react/docs/lists-and-keys.html">Lists and Keys</a>
</li>
<li>
<a href="/react/docs/forms.html">Forms</a>
</li>
<li>
<a href="/react/docs/lifting-state-up.html">Lifting State Up</a>
</li>
<li>
<a href="/react/docs/composition-vs-inheritance.html">Composition vs Inheritance</a>
</li>
<li>
<a href="/react/docs/thinking-in-react.html">Thinking In React</a>
</li>
</ul>
</div>
<div class="nav-docs-section">
<h3>Advanced Guides</h3>
<ul>
<li>
<a href="/react/docs/jsx-in-depth.html" class="active">JSX In Depth</a>
</li>
<li>
<a href="/react/docs/typechecking-with-proptypes.html">Typechecking With PropTypes</a>
</li>
<li>
<a href="/react/docs/refs-and-the-dom.html">Refs and the DOM</a>
</li>
<li>
<a href="/react/docs/uncontrolled-components.html">Uncontrolled Components</a>
</li>
<li>
<a href="/react/docs/optimizing-performance.html">Optimizing Performance</a>
</li>
<li>
<a href="/react/docs/react-without-es6.html">React Without ES6</a>
</li>
<li>
<a href="/react/docs/react-without-jsx.html">React Without JSX</a>
</li>
<li>
<a href="/react/docs/reconciliation.html">Reconciliation</a>
</li>
<li>
<a href="/react/docs/context.html">Context</a>
</li>
<li>
<a href="/react/docs/web-components.html">Web Components</a>
</li>
<li>
<a href="/react/docs/higher-order-components.html">Higher-Order Components</a>
</li>
</ul>
</div>
<div class="nav-docs-section">
<h3>Reference</h3>
<ul>
<li>
<a href="/react/docs/react-api.html">React</a>
<ul>
<li>
<a href="/react/docs/react-component.html">React.Component</a>
</li>
</ul>
</li>
<li>
<a href="/react/docs/react-dom.html">ReactDOM</a>
</li>
<li>
<a href="/react/docs/react-dom-server.html">ReactDOMServer</a>
</li>
<li>
<a href="/react/docs/dom-elements.html">DOM Elements</a>
</li>
<li>
<a href="/react/docs/events.html">SyntheticEvent</a>
</li>
<li>
<a href="/react/docs/addons.html">Add-Ons</a>
<ul>
<li>
<a href="/react/docs/perf.html">Performance Tools</a>
</li>
<li>
<a href="/react/docs/test-utils.html">Test Utilities</a>
</li>
<li>
<a href="/react/docs/animation.html">Animation</a>
</li>
<li>
<a href="/react/docs/create-fragment.html">Keyed Fragments</a>
</li>
<li>
<a href="/react/docs/update.html">Immutability Helpers</a>
</li>
<li>
<a href="/react/docs/pure-render-mixin.html">PureRenderMixin</a>
</li>
<li>
<a href="/react/docs/shallow-compare.html">Shallow Compare</a>
</li>
<li>
<a href="/react/docs/two-way-binding-helpers.html">Two-way Binding Helpers</a>
</li>
</ul>
</li>
</ul>
</div>
<!-- Contributing Nav -->
<div class="nav-docs-section">
<h3>Contributing</h3>
<ul>
<li>
<a href="/react/contributing/how-to-contribute.html">How to Contribute</a>
</li>
<li>
<a href="/react/contributing/codebase-overview.html">Codebase Overview</a>
</li>
<li>
<a href="/react/contributing/implementation-notes.html">Implementation Notes</a>
</li>
<li>
<a href="/react/contributing/design-principles.html">Design Principles</a>
</li>
</ul>
</div>
</div>
</section>
<footer class="nav-footer">
<section class="sitemap">
<a href="/react/" class="nav-home">
</a>
<div>
<h5><a href="/react/docs/">Docs</a></h5>
<a href="/react/docs/hello-world.html">Quick Start</a>
<a href="/react/docs/thinking-in-react.html">Thinking in React</a>
<a href="/react/tutorial/tutorial.html">Tutorial</a>
<a href="/react/docs/jsx-in-depth.html">Advanced Guides</a>
</div>
<div>
<h5><a href="/react/community/support.html">Community</a></h5>
<a href="http://stackoverflow.com/questions/tagged/reactjs" target="_blank">Stack Overflow</a>
<a href="https://discuss.reactjs.org/" target="_blank">Discussion Forum</a>
<a href="https://discord.gg/0ZcbPKXt5bZjGY5n" target="_blank">Reactiflux Chat</a>
<a href="https://www.facebook.com/react" target="_blank">Facebook</a>
<a href="https://twitter.com/reactjs" target="_blank">Twitter</a>
</div>
<div>
<h5><a href="/react/community/support.html">Resources</a></h5>
<a href="/react/community/conferences.html">Conferences</a>
<a href="/react/community/videos.html">Videos</a>
<a href="https://github.com/facebook/react/wiki/Examples" target="_blank">Examples</a>
<a href="https://github.com/facebook/react/wiki/Complementary-Tools" target="_blank">Complementary Tools</a>
</div>
<div>
<h5>More</h5>
<a href="/react/blog/">Blog</a>
<a href="https://github.com/facebook/react" target="_blank">GitHub</a>
<a href="http://facebook.github.io/react-native/" target="_blank">React Native</a>
<a href="/react/acknowledgements.html">Acknowledgements</a>
</div>
</section>
<a href="https://code.facebook.com/projects/" target="_blank" class="fbOpenSource">
<img src="/react/img/oss_logo.png" alt="Facebook Open Source" width="170" height="45"/>
</a>
<section class="copyright">
Copyright © 2017 Facebook Inc.
</section>
</footer>
</div>
<div id="fb-root"></div>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-41298772-1', 'facebook.github.io');
ga('send', 'pageview');
!function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src="https://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);}}(document,"script","twitter-wjs");
(function(d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); js.id = id;
js.src = "//connect.facebook.net/en_US/sdk.js#xfbml=1&version=v2.6&appId=623268441017527";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));
docsearch({
apiKey: '36221914cce388c46d0420343e0bb32e',
indexName: 'react',
inputSelector: '#algolia-doc-search'
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink