react.dev/docs/02.1-jsx-in-depth.md

id	title	layout	permalink	prev	next
jsx-in-depth	JSX in Depth	docs	jsx-in-depth.html	displaying-data.html	jsx-gotchas.html

JSX is a JavaScript XML syntax transform recommended for use with React.

Why JSX?

React works out of the box without JSX. Simply construct your markup using the functions on React.DOM. For example, here's how to construct a simple link:

var link = React.DOM.a({href: 'http://facebook.github.io/react'}, 'React');

We recommend using JSX for many reasons:

• It's easier to visualize the structure of the DOM.
• Designers are more comfortable making changes.
• It's familiar for those who have used MXML or XAML.

The Transform

JSX transforms from an XML-like syntax into native JavaScript. XML elements and attributes are transformed into function calls and objects, respectively.

var Nav;
// Input (JSX):
var app = <Nav color="blue" />;
// Output (JS):
var app = Nav({color:"blue"});

Notice that in order to use <Nav />, the Nav variable must be in scope.

JSX also allows specifying children using XML syntax:

var Nav, Profile;
// Input (JSX):
var app = <Nav color="blue"><Profile>click</Profile></Nav>;
// Output (JS):
var app = Nav({color:"blue"}, Profile(null, "click"));

Use the JSX Compiler to try out JSX and see how it desugars into native JavaScript.

If you want to use JSX, the Getting Started guide shows how to setup compilation.

Note:

Details about the code transform are given here to increase understanding, but your code should not rely on these implementation details.

React and JSX

React and JSX are independent technologies, but JSX was primarily built with React in mind. The two valid uses of JSX are:

• To construct instances of React DOM components (React.DOM.*).
• To construct instances of composite components created with React.createClass().

React DOM Components

To construct a <div> is to create a variable that refers to React.DOM.div.

var div = React.DOM.div;
var app = <div className="appClass">Hello, React!</div>;

React Composite Components

To construct an instance of a composite component, create a variable that references the class.

var MyComponent = React.createClass({/*...*/});
var app = <MyComponent someProperty={true} />;

See Multiple Components to learn more about using composite components.

Note:

Since JSX is JavaScript, identifiers such as class and for are discouraged as XML attribute names. Instead, React DOM components expect attributes like className and htmlFor, respectively.

DOM Convenience

Having to define variables for every type of DOM element can get tedious (e.g. var div, span, h1, h2, ...). JSX provides a convenience to address this problem by allowing you to specify a variable in an @jsx docblock field. JSX will use that field to find DOM components.

/**
 * @jsx React.DOM
 */
var Nav;
// Input (JSX):
var tree = <Nav><span /></Nav>;
// Output (JS):
var tree = Nav(null, React.DOM.span(null));

Remember:

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.

JavaScript Expressions

Attribute Expressions

To use a JavaScript expression as an attribute value, wrap the expression in a pair of curly braces ({}) instead of quotes ("").

// Input (JSX):
var person = <Person name={window.isLoggedIn ? window.name : ''} />;
// Output (JS):
var person = Person({name: window.isLoggedIn ? window.name : ''});

Child Expressions

Likewise, JavaScript expressions may be used to express children:

// Input (JSX):
var content = <Container>{window.isLoggedIn ? <Nav /> : <Login />}</Container>;
// Output (JS):
var content = Container(null, window.isLoggedIn ? Nav(null) : Login(null));

Comments

It's easy to add comments within your JSX; they're just JS expressions:

var content = <Container>{/* this is a comment */}<Nav /></Container>;

Tooling

Beyond the compilation step, JSX does not require any special tools.

• Many editors already include reasonable support for JSX (Vim, Emacs js2-mode).
  • JSX syntax highlighting is available for Sublime Text and other editors that support *.tmLanguage using the third-party JavaScript (JSX).tmLanguage.
• Linting provides accurate line numbers after compiling without sourcemaps.
• Elements use standard scoping so linters can find usage of out-of-scope components.

Prior Work

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:

• JSX is a simple syntactic transform.
• JSX neither provides nor requires a runtime library.
• JSX does not alter or add to the semantics of JavaScript.

JSX is similar to HTML, but not exactly the same. See JSX gotchas for some key differences.