JSX

Introduction

JSX is an XML-like syntax extension to ECMAScript without any defined semantics. It's NOT intended to be implemented by engines or browsers. It's NOT a proposal to incorporate JSX into the ECMAScript spec itself. It's intended to be used by various preprocessors (transpilers) to transform these tokens into standard ECMAScript.

// Using JSX to express UI components

var dropdown =

  <Dropdown>

    A dropdown list

    <Menu>

      <MenuItem>Do Something</MenuItem>

      <MenuItem>Do Something Fun!</MenuItem>

      <MenuItem>Do Something Else</MenuItem>

    </Menu>

  </Dropdown>;

render(dropdown); 

Rationale

The purpose of this specification is to define a concise and familiar syntax for defining tree structures with attributes. A generic but well defined syntax enables a community of independent parsers and syntax highlighters to conform to a single specification.

Embedding a new syntax in an existing language is a risky venture. Other syntax implementors or the existing language may introduce another incompatible syntax extension.

Through a stand-alone specification, we make it easier for implementors of other syntax extensions to consider JSX when designing their own syntax. This will hopefully allow various new syntax extensions to co-exist.

It is our intention to claim minimal syntactic real estate while keeping the syntax concise and familiar. That way we leave the door open for other extensions.

This specification does not attempt to comply with any XML or HTML specification. JSX is designed as an ECMAScript feature and the similarity to XML is only for familiarity.

1 JSX Definition

1.1 Modified Productions

JSX extends the PrimaryExpression in the ECMAScript (ECMA-262) grammar:

Syntax

PrimaryExpression :

JSXElement

JSXFragment

1.2 JSX Elements

Syntax

JSXElement :

JSXSelfClosingElement

JSXOpeningElement JSXChildrenopt JSXClosingElement

JSXSelfClosingElement :

< JSXElementName JSXAttributesopt / >

JSXOpeningElement :

< JSXElementName JSXAttributesopt >

JSXClosingElement :

< / JSXElementName >

JSXFragment :

< > JSXChildrenopt < / >

JSXElementName :

JSXIdentifier

JSXNamespacedName

JSXMemberExpression

JSXIdentifier :

IdentifierStart

JSXIdentifier IdentifierPart

JSXIdentifier [no WhiteSpace or Comment here] -

Note

The grammar of JSXIdentifier is not parameterized the same way Identifier is. This means that <await /> is still a valid production when "[await]" appears during the derivation.

JSXNamespacedName :

JSXIdentifier : JSXIdentifier

JSXMemberExpression :

JSXIdentifier . JSXIdentifier

JSXMemberExpression . JSXIdentifier

1.2.1 Static Semantics: Early Errors

JSXElement : JSXOpeningElement JSXChildrenopt JSXClosingElement

• It is a Syntax Error if the source text matched by the JSXElementName of JSXOpeningElement does not equal to the source text matched by the JSXElementName of JSXClosingElement.

1.3 JSX Attributes

Syntax

JSXAttributes :

JSXSpreadAttribute JSXAttributesopt

JSXAttribute JSXAttributesopt

JSXSpreadAttribute :

{ ... AssignmentExpression }

JSXAttribute :

JSXAttributeName JSXAttributeInitializeropt

JSXAttributeName :

JSXIdentifier

JSXNamespacedName

JSXAttributeInitializer :

= JSXAttributeValue

JSXAttributeValue :

" JSXDoubleStringCharactersopt "

' JSXSingleStringCharactersopt '

{ AssignmentExpression }

JSXElement

JSXFragment

JSXDoubleStringCharacters ::

JSXDoubleStringCharacter JSXDoubleStringCharactersopt

JSXDoubleStringCharacter ::

JSXStringCharacter but not "

JSXSingleStringCharacters ::

JSXSingleStringCharacter JSXSingleStringCharactersopt

JSXSingleStringCharacter ::

JSXStringCharacter but not '

1.4 JSX Children

Syntax

JSXChildren :

JSXChild JSXChildrenopt

JSXChild :

JSXText

JSXElement

JSXFragment

{ JSXChildExpressionopt }

JSXText ::

JSXTextCharacter JSXTextopt

JSXTextCharacter ::

JSXStringCharacter but not one of { or < or > or }

JSXChildExpression :

AssignmentExpression

... AssignmentExpression

1.5 JSX Strings

1.5.1 JSX String Characters

Historically, string characters within JSXAttributeValue and JSXText are extended to allow the presence of HTML character references to make copy-pasting between HTML and JSX easier, at the cost of not supporting \ EscapeSequence of ECMAScript's StringLiteral. We may revisit this decision in the future.

Syntax

JSXStringCharacter ::

SourceCharacter but not one of HTMLCharacterReference

1.5.2 HTML Character References

Note 1

The grammars here followed the living HTML standard.

Syntax

HTMLCharacterReference ::

HTMLDecimalCharacterReference

HTMLHexCharacterReference

HTMLNamedCharacterReference

HTMLDecimalCharacterReference ::

& # DecimalDigits but only if MV of DecimalDigits ≦ 0x10FFFF ;

HTMLHexCharacterReference ::

& # x HexDigits but only if MV of HexDigits ≦ 0x10FFFF ;

HTMLNamedCharacterReference ::

& HTMLNamedCharacterReferenceName ;

HTMLNamedCharacterReferenceName ::

List of 252 character entity references defined in HTML4 standard

Note 2

This means that the later expansion of this list to 2231 named character references since HTML5 are intentionally excluded from the support.

The list of 252 character entity references defined in HTML4 standard can be found at here.

1.5.3 JSX String Definition

Syntax

JSXString :

JSXDoubleStringCharacters

JSXSingleStringCharacters

JSXText

1.5.3.1 Static Semantics: SV

An implementation may convert JSXString into a ECMAScript String value. In order to do this, JSX extends the syntax-directed operation SV to JSXStringCharacter:

• The SV of JSXStringCharacter :: SourceCharacter is the result of performing UTF16EncodeCodePoint on the code point matched by SourceCharacter.

• The SV of HTMLDecimalCharacterReference :: & # DecimalDigits ; is the same as the result of performing UTF16EncodeCodePoint on the MV of DecimalDigits

• The SV of HTMLHexCharacterReference :: & # x HexDigits ; is the same as the result of performing UTF16EncodeCodePoint on the MV of HexDigits

• The SV of HTMLNamedCharacterReference :: & HTMLNamedCharacterReferenceName ; is the same as the result of performing UTF16EncodeCodePoint on the code points matched by HTMLNamedCharacterReferenceName according the implementation-defined list of names.

The exact approach to fulfill the extended sematics is implementation-defined.

Note

For example, at the time of writing, Babel implemented this in its JSX parser, while TypeScript implemented it via a JSX transformer.

A Why not Template Literals?

ECMAScript 6th Edition (ECMA-262) introduces template literals which are intended to be used for embedding DSL in ECMAScript. Why not just use that instead of inventing a syntax that's not part of ECMAScript?

Template literals work well for long embedded DSLs. Unfortunately the syntax noise is substantial when you exit in and out of embedded arbitrary ECMAScript expressions with identifiers in scope.

// Template Literals

var box = jsx`

  <${Box}>

    ${

      shouldShowAnswer(user) ?

      jsx`<${Answer} value=${false}>no</${Answer}>` :

      jsx`

        <${Box.Comment}>

         Text Content

        </${Box.Comment}>

      `

    }

  </${Box}>

`; 

It would be possible to use template literals as a syntactic entry point and change the semantics inside the template literal to allow embedded scripts that can be evaluated in scope: 

// Template Literals with embedded JSX

var box = jsx`

  <Box>

    {

      shouldShowAnswer(user) ?

      <Answer value={false}>no</Answer> :

      <Box.Comment>

         Text Content

      </Box.Comment>

    }

  </Box>

`; 

However, this would lead to further divergence. Tooling that is built around the assumptions imposed by template literals wouldn't work. It would undermine the meaning of template literals. It would be necessary to define how JSX behaves within the rest of the ECMAScript grammar within the template literal anyway.

Therefore it's better to introduce JSX as an entirely new type of PrimaryExpression:

// JSX

var box =

  <Box>

    {

      shouldShowAnswer(user) ?

      <Answer value={false}>no</Answer> :

      <Box.Comment>

         Text Content

      </Box.Comment>

    }

  </Box>; 

Note

Don't you love the syntax highlighting here? ;)

B Why not JXON?

Another alternative would be to use object initializers (similar to JXON). Unfortunately, the balanced braces do not give great syntactic hints for where an element starts and ends in large trees. Balanced named tags is a critical syntactic feature of the XML-style notation.

C Prior Art

The JSX syntax is similar to the E4X Specification (ECMA-357). E4X is a deprecated specification with deep reaching semantic meaning. JSX partially overlaps with a tiny subset of the E4X syntax. However, JSX has no relation to the E4X specification.

D License

Copyright (c) 2014 - present, Meta Platforms, Inc. All rights reserved.

This work is licensed under a Creative Commons Attribution 4.0 International License.