JSX in Depth Edit on GitHub

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

Note:

Don't forget the /** @jsx React.DOM */ pragma at the beginning of your file! This tells JSX to process the file for React.

If you don't include the pragma, your source will remain untouched, so it's safe to run the JSX transformer on all JS files in your codebase if you want to.

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, and the HTML to JSX converter to convert your existing HTML to JSX.

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} />;

JSX will infer the component's name from the variable assignment and specify the class's displayName accordingly.

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. You just need to be careful to put {} around the comments when you are within the children section of a tag.

var content = (
  <Nav>
    {/* child comment, put {} around */}
    <Person
      /* multi
         line
         comment */
      name={window.isLoggedIn ? window.name : ''} // end of line comment
    />
  </Nav>
);

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.