Files
react/docs/jsx-in-depth.html
T
Vjeux ee5805da65 Christopher Chedeau vjeux Document isMounted … 30e16e4
Nick Thompson	nick-thompson	Clarify componentWillMount behavior	542f20b
Cheng Lou	chenglou	docs fix back link in Examples	6b15ad5
Cheng Lou	chenglou	docs add jsx->js tab to live editors	7ac5f3c
Paul O’Shannessy	zpao	Normalize line endings	6b1c6be
Ben Alpert	spicyj	Update homepage for new JSX/JS editor	761e1c8
Ben Alpert	spicyj	Properly clear live editor on JSX compile failure	d3fc5ad
Ben Alpert	spicyj	Simplify live editor execution logic	c7f0663
Cheng Lou	chenglou	[docs] Tweak frontpage first example and jsx-compiler example	8c8841c
Christoph Pojer	cpojer	Update propTypes documentation.	b66fbde
Jean Lauliac	jeanlauliac	Update broken link in 'why react' article	341d292
Jean Lauliac	jeanlauliac	Normalize internal links in 'why react' article	0681d13
aymanosman	aymanosman	Fix typo	09650e1
Bob Eagan	bobeagan	fix incorrect link	2edb76f
Bob Eagan	bobeagan	add hash link for lifecycle section of working with the browser page	3db3460
Pete Hunt	petehunt	remove references to react-page	3120192
Ben Alpert	spicyj	Fix docs typo	6e4ddfd
Paul O’Shannessy	zpao	Fix animation example code …	dd66223
Eric Schoffstall	Contra	fix grammar mistake	64ac427
Kunal Mehta	kmeht	Add documentation about React.renderComponent …	f970453
Christopher Chedeau	vjeux	s/Mock DOM/Virtual DOM/ …	22772c9
Ben Alpert	spicyj	Disable CodeMirror smart indentation …	571d173
Ben Alpert	spicyj	[docs] Fix comma splice	3810c83
2014-02-02 03:58:18 +01:00

533 lines
25 KiB
HTML

<!DOCTYPE html>
<!--[if IE]><![endif]-->
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<title>React | JSX in Depth</title>
<meta name="viewport" content="width=device-width">
<meta property="og:title" content="React | JSX in Depth" />
<meta property="og:type" content="website" />
<meta property="og:url" content="http://facebook.github.io/react/docs/jsx-in-depth.html" />
<meta property="og:image" content="http://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="http://facebook.github.io/react/feed.xml">
<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 type="text/javascript" src="//use.typekit.net/vqa1hcx.js"></script>
<script type="text/javascript">try{Typekit.load();}catch(e){}</script>
<!--[if lte IE 8]>
<script type="text/javascript" src="/react/js/html5shiv.min.js"></script>
<script type="text/javascript" src="/react/js/es5-shim.min.js"></script>
<script type="text/javascript" src="/react/js/es5-sham.min.js"></script>
<![endif]-->
<script type="text/javascript" src="/react/js/codemirror.js"></script>
<script type="text/javascript" src="/react/js/javascript.js"></script>
<script type="text/javascript" src="/react/js/react.min.js"></script>
<script type="text/javascript" src="/react/js/JSXTransformer.js"></script>
<script type="text/javascript" src="/react/js/live_editor.js"></script>
<script type="text/javascript" src="/react/js/showdown.js"></script>
</head>
<body>
<div class="container">
<div class="nav-main">
<div class="wrap">
<a class="nav-home" href="/react/index.html">
<img class="nav-logo" alt="" src="/react/img/logo_small.png" width="38" height="38">
React
</a>
<ul class="nav-site">
<li><a href="/react/docs/getting-started.html" class="active">docs</a></li>
<li><a href="/react/support.html">support</a></li>
<li><a href="/react/downloads.html">download</a></li>
<li><a href="/react/blog/">blog</a></li>
<li><a href="http://github.com/facebook/react">github</a>
</ul>
</div>
</div>
<section class="content wrap documentationContent">
<div class="nav-docs">
<!-- Docs Nav -->
<div class="nav-docs-section">
<h3>Quick Start</h3>
<ul>
<li>
<a href="/react/docs/getting-started.html">
Getting Started
</a>
</li>
<li>
<a href="/react/docs/tutorial.html">
Tutorial
</a>
</li>
<li>
<a href="/react/docs/videos.html">
Videos
</a>
</li>
</ul>
</div>
<div class="nav-docs-section">
<h3>Guides</h3>
<ul>
<li>
<a href="/react/docs/why-react.html">
Why React?
</a>
</li>
<li>
<a href="/react/docs/displaying-data.html">
Displaying Data
</a>
<ul>
<li>
<a href="/react/docs/jsx-in-depth.html" class="active">
JSX in Depth
</a>
</li>
<li>
<a href="/react/docs/jsx-gotchas.html">
JSX Gotchas
</a>
</li>
</ul>
</li>
<li>
<a href="/react/docs/interactivity-and-dynamic-uis.html">
Interactivity and Dynamic UIs
</a>
</li>
<li>
<a href="/react/docs/multiple-components.html">
Multiple Components
</a>
</li>
<li>
<a href="/react/docs/reusable-components.html">
Reusable Components
</a>
</li>
<li>
<a href="/react/docs/forms.html">
Forms
</a>
</li>
<li>
<a href="/react/docs/working-with-the-browser.html">
Working With the Browser
</a>
<ul>
<li>
<a href="/react/docs/more-about-refs.html">
More About Refs
</a>
</li>
</ul>
</li>
<li>
<a href="/react/docs/tooling-integration.html">
Tooling Integration
</a>
</li>
<li>
<a href="/react/docs/addons.html">
Add-Ons
</a>
<ul>
<li>
<a href="/react/docs/animation.html">
Animation
</a>
</li>
<li>
<a href="/react/docs/two-way-binding-helpers.html">
Two-Way Binding Helpers
</a>
</li>
<li>
<a href="/react/docs/class-name-manipulation.html">
Class Name Manipulation
</a>
</li>
</ul>
</li>
<li>
<a href="/react/docs/examples.html">
Examples
</a>
</li>
</ul>
</div>
<div class="nav-docs-section">
<h3>Reference</h3>
<ul>
<li>
<a href="/react/docs/top-level-api.html">
Top-Level API
</a>
</li>
<li>
<a href="/react/docs/component-api.html">
Component API
</a>
</li>
<li>
<a href="/react/docs/component-specs.html">
Component Specs and Lifecycle
</a>
</li>
<li>
<a href="/react/docs/tags-and-attributes.html">
Supported Tags and Attributes
</a>
</li>
<li>
<a href="/react/docs/events.html">
Event System
</a>
</li>
<li>
<a href="/react/docs/dom-differences.html">
DOM Differences
</a>
</li>
<li>
<a href="/react/docs/special-non-dom-attributes.html">
Special Non-DOM attributes
</a>
</li>
<li>
<a href="/react/docs/reconciliation.html">
Reconciliation
</a>
</li>
</ul>
</div>
<!-- Tips Nav -->
<div class="nav-docs-section">
<h3>Tips</h3>
<ul>
<li>
<a href="/react/tips/introduction.html">Introduction</a>
</li>
<li>
<a href="/react/tips/inline-styles.html">Inline Styles</a>
</li>
<li>
<a href="/react/tips/if-else-in-JSX.html">If-Else in JSX</a>
</li>
<li>
<a href="/react/tips/self-closing-tag.html">Self-Closing Tag</a>
</li>
<li>
<a href="/react/tips/maximum-number-of-jsx-root-nodes.html">Maximum Number of JSX Root Nodes</a>
</li>
<li>
<a href="/react/tips/style-props-value-px.html">Shorthand for Specifying Pixel Values in style props</a>
</li>
<li>
<a href="/react/tips/children-props-type.html">Type of the Children props</a>
</li>
<li>
<a href="/react/tips/controlled-input-null-value.html">Value of null for Controlled Input</a>
</li>
<li>
<a href="/react/tips/componentWillReceiveProps-not-triggered-after-mounting.html">componentWillReceiveProps Not Triggered After Mounting</a>
</li>
<li>
<a href="/react/tips/props-in-getInitialState-as-anti-pattern.html">Props in getInitialState Is an Anti-Pattern</a>
</li>
<li>
<a href="/react/tips/dom-event-listeners.html">DOM Event Listeners in a Component</a>
</li>
<li>
<a href="/react/tips/initial-ajax.html">Load Initial Data via AJAX</a>
</li>
<li>
<a href="/react/tips/false-in-jsx.html">False in JSX</a>
</li>
<li>
<a href="/react/tips/communicate-between-components.html">Communicate Between Components</a>
</li>
<li>
<a href="/react/tips/expose-component-functions.html">Expose Component Functions</a>
</li>
</ul>
</div>
</div>
<div class="inner-content">
<h1>JSX in Depth</h1>
<div class="subHeader"></div>
<p>JSX is a JavaScript XML syntax transform recommended for use
with React.</p>
<blockquote>
<p>Note:</p>
<p>Don&#39;t forget the <code>/** @jsx React.DOM */</code> pragma at the beginning of your file! This tells JSX to process the file for React.</p>
<p>If you don&#39;t include the pragma, your source will remain untouched, so it&#39;s safe to run the JSX transformer on all JS files in your codebase if you want to.</p>
</blockquote>
<h2><a class="anchor" name="why-jsx"></a>Why JSX? <a class="hash-link" href="#why-jsx">#</a></h2>
<p>React works out of the box without JSX. Simply construct your markup using the
functions on <code>React.DOM</code>. For example, here&#39;s how to construct a simple link:</p>
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="kd">var</span> <span class="nx">link</span> <span class="o">=</span> <span class="nx">React</span><span class="p">.</span><span class="nx">DOM</span><span class="p">.</span><span class="nx">a</span><span class="p">({</span><span class="nx">href</span><span class="o">:</span> <span class="s1">&#39;http://facebook.github.io/react&#39;</span><span class="p">},</span> <span class="s1">&#39;React&#39;</span><span class="p">);</span>
</code></pre></div>
<p>We recommend using JSX for many reasons:</p>
<ul>
<li>It&#39;s easier to visualize the structure of the DOM.</li>
<li>Designers are more comfortable making changes.</li>
<li>It&#39;s familiar for those who have used MXML or XAML.</li>
</ul>
<h2><a class="anchor" name="the-transform"></a>The Transform <a class="hash-link" href="#the-transform">#</a></h2>
<p>JSX transforms from an XML-like syntax into native JavaScript. XML elements and
attributes are transformed into function calls and objects, respectively.</p>
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="kd">var</span> <span class="nx">Nav</span><span class="p">;</span>
<span class="c1">// Input (JSX):</span>
<span class="kd">var</span> <span class="nx">app</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">Nav</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 class="c1">// Output (JS):</span>
<span class="kd">var</span> <span class="nx">app</span> <span class="o">=</span> <span class="nx">Nav</span><span class="p">({</span><span class="nx">color</span><span class="o">:</span><span class="s2">&quot;blue&quot;</span><span class="p">});</span>
</code></pre></div>
<p>Notice that in order to use <code>&lt;Nav /&gt;</code>, the <code>Nav</code> variable must be in scope.</p>
<p>JSX also allows specifying children using XML syntax:</p>
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="kd">var</span> <span class="nx">Nav</span><span class="p">,</span> <span class="nx">Profile</span><span class="p">;</span>
<span class="c1">// Input (JSX):</span>
<span class="kd">var</span> <span class="nx">app</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">Nav</span> <span class="nx">color</span><span class="o">=</span><span class="s2">&quot;blue&quot;</span><span class="o">&gt;&lt;</span><span class="nx">Profile</span><span class="o">&gt;</span><span class="nx">click</span><span class="o">&lt;</span><span class="err">/Profile&gt;&lt;/Nav&gt;;</span>
<span class="c1">// Output (JS):</span>
<span class="kd">var</span> <span class="nx">app</span> <span class="o">=</span> <span class="nx">Nav</span><span class="p">({</span><span class="nx">color</span><span class="o">:</span><span class="s2">&quot;blue&quot;</span><span class="p">},</span> <span class="nx">Profile</span><span class="p">(</span><span class="kc">null</span><span class="p">,</span> <span class="s2">&quot;click&quot;</span><span class="p">));</span>
</code></pre></div>
<p>Use the <a href="/react/jsx-compiler.html">JSX Compiler</a> to try out JSX and see how it
desugars into native JavaScript, and the
<a href="/react/html-jsx.html">HTML to JSX converter</a> to convert your existing HTML to
JSX.</p>
<p>If you want to use JSX, the <a href="/react/docs/getting-started.html">Getting Started</a> guide shows
how to setup compilation.</p>
<blockquote>
<p>Note:</p>
<p>Details about the code transform are given here to increase understanding, but
your code should not rely on these implementation details.</p>
</blockquote>
<h2><a class="anchor" name="react-and-jsx"></a>React and JSX <a class="hash-link" href="#react-and-jsx">#</a></h2>
<p>React and JSX are independent technologies, but JSX was primarily built with
React in mind. The two valid uses of JSX are:</p>
<ul>
<li>To construct instances of React DOM components (<code>React.DOM.*</code>).</li>
<li>To construct instances of composite components created with
<code>React.createClass()</code>.</li>
</ul>
<h3><a class="anchor" name="react-dom-components"></a>React DOM Components <a class="hash-link" href="#react-dom-components">#</a></h3>
<p>To construct a <code>&lt;div&gt;</code> is to create a variable that refers to <code>React.DOM.div</code>.</p>
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="kd">var</span> <span class="nx">div</span> <span class="o">=</span> <span class="nx">React</span><span class="p">.</span><span class="nx">DOM</span><span class="p">.</span><span class="nx">div</span><span class="p">;</span>
<span class="kd">var</span> <span class="nx">app</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">div</span> <span class="nx">className</span><span class="o">=</span><span class="s2">&quot;appClass&quot;</span><span class="o">&gt;</span><span class="nx">Hello</span><span class="p">,</span> <span class="nx">React</span><span class="o">!&lt;</span><span class="err">/div&gt;;</span>
</code></pre></div><h3><a class="anchor" name="react-composite-components"></a>React Composite Components <a class="hash-link" href="#react-composite-components">#</a></h3>
<p>To construct an instance of a composite component, create a variable that
references the class.</p>
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="kd">var</span> <span class="nx">MyComponent</span> <span class="o">=</span> <span class="nx">React</span><span class="p">.</span><span class="nx">createClass</span><span class="p">({</span><span class="cm">/*...*/</span><span class="p">});</span>
<span class="kd">var</span> <span class="nx">app</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">MyComponent</span> <span class="nx">someProperty</span><span class="o">=</span><span class="p">{</span><span class="kc">true</span><span class="p">}</span> <span class="o">/&gt;</span><span class="p">;</span>
</code></pre></div>
<p>JSX will infer the component&#39;s name from the variable assignment and specify
the class&#39;s <a href="/react/docs/component-specs.html#displayName">displayName</a> accordingly.</p>
<p>See <a href="/react/docs/multiple-components.html">Multiple Components</a> to learn more about using composite components.</p>
<blockquote>
<p>Note:</p>
<p>Since JSX is JavaScript, identifiers such as <code>class</code> and <code>for</code> are discouraged
as XML attribute names. Instead, React DOM components expect attributes like
<code>className</code> and <code>htmlFor</code>, respectively.</p>
</blockquote>
<h2><a class="anchor" name="dom-convenience"></a>DOM Convenience <a class="hash-link" href="#dom-convenience">#</a></h2>
<p>Having to define variables for every type of DOM element can get tedious
(e.g. <code>var div, span, h1, h2, ...</code>). JSX provides a convenience to address this
problem by allowing you to specify a variable in an <code>@jsx</code> docblock field. JSX
will use that field to find DOM components.</p>
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="cm">/**</span>
<span class="cm"> * @jsx React.DOM</span>
<span class="cm"> */</span>
<span class="kd">var</span> <span class="nx">Nav</span><span class="p">;</span>
<span class="c1">// Input (JSX):</span>
<span class="kd">var</span> <span class="nx">tree</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">Nav</span><span class="o">&gt;&lt;</span><span class="nx">span</span> <span class="o">/&gt;&lt;</span><span class="err">/Nav&gt;;</span>
<span class="c1">// Output (JS):</span>
<span class="kd">var</span> <span class="nx">tree</span> <span class="o">=</span> <span class="nx">Nav</span><span class="p">(</span><span class="kc">null</span><span class="p">,</span> <span class="nx">React</span><span class="p">.</span><span class="nx">DOM</span><span class="p">.</span><span class="nx">span</span><span class="p">(</span><span class="kc">null</span><span class="p">));</span>
</code></pre></div>
<blockquote>
<p>Remember:</p>
<p>JSX simply transforms elements into function calls and has no notion of the
DOM. The docblock parameter is only a convenience to resolve the most commonly
used elements. In general, JSX has no notion of the DOM.</p>
</blockquote>
<h2><a class="anchor" name="javascript-expressions"></a>JavaScript Expressions <a class="hash-link" href="#javascript-expressions">#</a></h2><h3><a class="anchor" name="attribute-expressions"></a>Attribute Expressions <a class="hash-link" href="#attribute-expressions">#</a></h3>
<p>To use a JavaScript expression as an attribute value, wrap the expression in a
pair of curly braces (<code>{}</code>) instead of quotes (<code>&quot;&quot;</code>).</p>
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="c1">// Input (JSX):</span>
<span class="kd">var</span> <span class="nx">person</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">Person</span> <span class="nx">name</span><span class="o">=</span><span class="p">{</span><span class="nb">window</span><span class="p">.</span><span class="nx">isLoggedIn</span> <span class="o">?</span> <span class="nb">window</span><span class="p">.</span><span class="nx">name</span> <span class="o">:</span> <span class="s1">&#39;&#39;</span><span class="p">}</span> <span class="o">/&gt;</span><span class="p">;</span>
<span class="c1">// Output (JS):</span>
<span class="kd">var</span> <span class="nx">person</span> <span class="o">=</span> <span class="nx">Person</span><span class="p">({</span><span class="nx">name</span><span class="o">:</span> <span class="nb">window</span><span class="p">.</span><span class="nx">isLoggedIn</span> <span class="o">?</span> <span class="nb">window</span><span class="p">.</span><span class="nx">name</span> <span class="o">:</span> <span class="s1">&#39;&#39;</span><span class="p">});</span>
</code></pre></div><h3><a class="anchor" name="child-expressions"></a>Child Expressions <a class="hash-link" href="#child-expressions">#</a></h3>
<p>Likewise, JavaScript expressions may be used to express children:</p>
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="c1">// Input (JSX):</span>
<span class="kd">var</span> <span class="nx">content</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">Container</span><span class="o">&gt;</span><span class="p">{</span><span class="nb">window</span><span class="p">.</span><span class="nx">isLoggedIn</span> <span class="o">?</span> <span class="o">&lt;</span><span class="nx">Nav</span> <span class="o">/&gt;</span> <span class="o">:</span> <span class="o">&lt;</span><span class="nx">Login</span> <span class="o">/&gt;</span><span class="p">}</span><span class="o">&lt;</span><span class="err">/Container&gt;;</span>
<span class="c1">// Output (JS):</span>
<span class="kd">var</span> <span class="nx">content</span> <span class="o">=</span> <span class="nx">Container</span><span class="p">(</span><span class="kc">null</span><span class="p">,</span> <span class="nb">window</span><span class="p">.</span><span class="nx">isLoggedIn</span> <span class="o">?</span> <span class="nx">Nav</span><span class="p">(</span><span class="kc">null</span><span class="p">)</span> <span class="o">:</span> <span class="nx">Login</span><span class="p">(</span><span class="kc">null</span><span class="p">));</span>
</code></pre></div><h3><a class="anchor" name="comments"></a>Comments <a class="hash-link" href="#comments">#</a></h3>
<p>It&#39;s easy to add comments within your JSX; they&#39;re just JS expressions:</p>
<div class="highlight"><pre><code class="javascript language-javascript" data-lang="javascript"><span class="kd">var</span> <span class="nx">content</span> <span class="o">=</span> <span class="o">&lt;</span><span class="nx">Container</span><span class="o">&gt;</span><span class="p">{</span><span class="cm">/* this is a comment */</span><span class="p">}</span><span class="o">&lt;</span><span class="nx">Nav</span> <span class="o">/&gt;&lt;</span><span class="err">/Container&gt;;</span>
</code></pre></div><h2><a class="anchor" name="prior-work"></a>Prior Work <a class="hash-link" href="#prior-work">#</a></h2>
<p>JSX is similar to several other JavaScript embedded XML language
proposals/projects. Some of the features of JSX that distinguish it from similar
efforts include:</p>
<ul>
<li>JSX is a simple syntactic transform.</li>
<li>JSX neither provides nor requires a runtime library.</li>
<li>JSX does not alter or add to the semantics of JavaScript.</li>
</ul>
<p>JSX is similar to HTML, but not exactly the same. See <a href="/react/docs/jsx-gotchas.html">JSX gotchas</a> for some key differences.</p>
<div class="docs-prevnext">
<a class="docs-prev" href="/react/docs/displaying-data.html">&larr; Prev</a>
<a class="docs-next" href="/react/docs/jsx-gotchas.html">Next &rarr;</a>
</div>
<div class="fb-comments" data-width="650" data-num-posts="10" data-href="http://facebook.github.io/react/docs/jsx-in-depth.html"></div>
</div>
</section>
<footer class="wrap">
<div class="left">A Facebook &amp; Instagram collaboration.</div>
<div class="right">&copy; 2014 Facebook Inc.</div>
</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/all.js#xfbml=1&appId=623268441017527";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));
</script>
</body>
</html>