JSX is an embeddable XML-like syntax.\nIt is meant to be transformed into valid JavaScript, though the semantics of that transformation are implementation-specific.\nJSX rose to popularity with the React framework, but has since seen other implementations as well.\nTypeScript supports embedding, type checking, and compiling JSX directly to JavaScript.
\nIn order to use JSX you must do two things.
\n.tsx extensionjsx optionTypeScript ships with three JSX modes: preserve, react, and react-native.\nThese modes only affect the emit stage - type checking is unaffected.\nThe preserve mode will keep the JSX as part of the output to be further consumed by another transform step (e.g. Babel).\nAdditionally the output will have a .jsx file extension.\nThe react mode will emit React.createElement, does not need to go through a JSX transformation before use, and the output will have a .js file extension.\nThe react-native mode is the equivalent of preserve in that it keeps all JSX, but the output will instead have a .js file extension.
| Mode | \nInput | \nOutput | \nOutput File Extension | \n
|---|---|---|---|
preserve | \n<div /> | \n<div /> | \n.jsx | \n
react | \n<div /> | \nReact.createElement(\"div\") | \n.js | \n
react-native | \n<div /> | \n<div /> | \n.js | \n
You can specify this mode using either the --jsx command line flag or the corresponding option in your tsconfig.json file.
\n\n*Note: You can specify the JSX factory function to use when targeting react JSX emit with
\n--jsxFactoryoption (defaults toReact.createElement)
as operatorRecall how to write a type assertion:
\n\ntsvar foo = <foo>bar;
This asserts the variable bar to have the type foo.\nSince TypeScript also uses angle brackets for type assertions, combining it with JSX’s syntax would introduce certain parsing difficulties. As a result, TypeScript disallows angle bracket type assertions in .tsx files.
Since the above syntax cannot be used in .tsx files, an alternate type assertion operator should be used: as.\nThe example can easily be rewritten with the as operator.
\ntsvar foo = bar as foo;
The as operator is available in both .ts and .tsx files, and is identical in behavior to the angle-bracket type assertion style.
In order to understand type checking with JSX, you must first understand the difference between intrinsic elements and value-based elements.\nGiven a JSX expression <expr />, expr may either refer to something intrinsic to the environment (e.g. a div or span in a DOM environment) or to a custom component that you’ve created.\nThis is important for two reasons:
React.createElement(\"div\")), whereas a component you’ve created is not (React.createElement(MyComponent)).TypeScript uses the same convention that React does for distinguishing between these.\nAn intrinsic element always begins with a lowercase letter, and a value-based element always begins with an uppercase letter.
\nIntrinsic elements are looked up on the special interface JSX.IntrinsicElements.\nBy default, if this interface is not specified, then anything goes and intrinsic elements will not be type checked.\nHowever, if this interface is present, then the name of the intrinsic element is looked up as a property on the JSX.IntrinsicElements interface.\nFor example:
\ntsdeclare namespace JSX {\n interface IntrinsicElements {\n foo: any;\n }\n}\n\n<foo />; // ok\n<bar />; // error
In the above example, <foo /> will work fine but <bar /> will result in an error since it has not been specified on JSX.IntrinsicElements.
\n\nNote: You can also specify a catch-all string indexer on
\nJSX.IntrinsicElementsas follows:
\ntsdeclare namespace JSX {\n interface IntrinsicElements {\n [elemName: string]: any;\n }\n}
Value-based elements are simply looked up by identifiers that are in scope.
\n\ntsimport MyComponent from \"./myComponent\";\n\n<MyComponent />; // ok\n<SomeOtherComponent />; // error
There are two ways to define a value-based element:
\nBecause these two types of value-based elements are indistinguishable from each other in a JSX expression, first TS tries to resolve the expression as a Function Component using overload resolution. If the process succeeds, then TS finishes resolving the expression to its declaration. If the value fails to resolve as a Function Component, TS will then try to resolve it as a class component. If that fails, TS will report an error.
\nAs the name suggests, the component is defined as a JavaScript function where its first argument is a props object.\nTS enforces that its return type must be assignable to JSX.Element.
\ntsinterface FooProp {\n name: string;\n X: number;\n Y: number;\n}\n\ndeclare function AnotherComponent(prop: {name: string});\nfunction ComponentFoo(prop: FooProp) {\n return <AnotherComponent name={prop.name} />;\n}\n\nconst Button = (prop: {value: string}, context: { color: string }) => <button>
Because a Function Component is simply a JavaScript function, function overloads may be used here as well:
\n\ntsinterface ClickableProps {\n children: JSX.Element[] | JSX.Element\n}\n\ninterface HomeProps extends ClickableProps {\n home: JSX.Element;\n}\n\ninterface SideProps extends ClickableProps {\n side: JSX.Element | string;\n}\n\nfunction MainButton(prop: HomeProps): JSX.Element;\nfunction MainButton(prop: SideProps): JSX.Element {\n ...\n}
\n\nNote: Function Components were formerly known as Stateless Function Components (SFC). As Function Components can no longer be considered stateless in recent versions of react, the type
\nSFCand its aliasStatelessComponentwere deprecated.
It is possible to define the type of a class component.\nHowever, to do so it is best to understand two new terms: the element class type and the element instance type.
\nGiven <Expr />, the element class type is the type of Expr.\nSo in the example above, if MyComponent was an ES6 class the class type would be that class’s constructor and statics.\nIf MyComponent was a factory function, the class type would be that function.
Once the class type is established, the instance type is determined by the union of the return types of the class type’s construct or call signatures (whichever is present).\nSo again, in the case of an ES6 class, the instance type would be the type of an instance of that class, and in the case of a factory function, it would be the type of the value returned from the function.
\n\ntsclass MyComponent {\n render() {}\n}\n\n// use a construct signature\nvar myComponent = new MyComponent();\n\n// element class type => MyComponent\n// element instance type => { render: () => void }\n\nfunction MyFactoryFunction() {\n return {\n render: () => {}\n };\n}\n\n// use a call signature\nvar myComponent = MyFactoryFunction();\n\n// element class type => FactoryFunction\n// element instance type => { render: () => void }
The element instance type is interesting because it must be assignable to JSX.ElementClass or it will result in an error.\nBy default JSX.ElementClass is {}, but it can be augmented to limit the use of JSX to only those types that conform to the proper interface.
\ntsdeclare namespace JSX {\n interface ElementClass {\n render: any;\n }\n}\n\nclass MyComponent {\n render() {}\n}\nfunction MyFactoryFunction() {\n return { render: () => {} };\n}\n\n<MyComponent />; // ok\n<MyFactoryFunction />; // ok\n\nclass NotAValidComponent {}\nfunction NotAValidFactoryFunction() {\n return {};\n}\n\n<NotAValidComponent />; // error\n<NotAValidFactoryFunction />; // error
The first step to type checking attributes is to determine the element attributes type.\nThis is slightly different between intrinsic and value-based elements.
\nFor intrinsic elements, it is the type of the property on JSX.IntrinsicElements
\ntsdeclare namespace JSX {\n interface IntrinsicElements {\n foo: { bar?: boolean };\n }\n}\n\n// element attributes type for 'foo' is '{bar?: boolean}'\n<foo bar />;
For value-based elements, it is a bit more complex.\nIt is determined by the type of a property on the element instance type that was previously determined.\nWhich property to use is determined by JSX.ElementAttributesProperty.\nIt should be declared with a single property.\nThe name of that property is then used.\nAs of TypeScript 2.8, if JSX.ElementAttributesProperty is not provided, the type of first parameter of the class element’s constructor or Function Component’s call will be used instead.
\ntsdeclare namespace JSX {\n interface ElementAttributesProperty {\n props; // specify the property name to use\n }\n}\n\nclass MyComponent {\n // specify the property on the element instance type\n props: {\n foo?: string;\n };\n}\n\n// element attributes type for 'MyComponent' is '{foo?: string}'\n<MyComponent foo=\"bar\" />;
The element attribute type is used to type check the attributes in the JSX.\nOptional and required properties are supported.
\n\ntsdeclare namespace JSX {\n interface IntrinsicElements {\n foo: { requiredProp: string; optionalProp?: number };\n }\n}\n\n<foo requiredProp=\"bar\" />; // ok\n<foo requiredProp=\"bar\" optionalProp={0} />; // ok\n<foo />; // error, requiredProp is missing\n<foo requiredProp={0} />; // error, requiredProp should be a string\n<foo requiredProp=\"bar\" unknownProp />; // error, unknownProp does not exist\n<foo requiredProp=\"bar\" some-unknown-prop />; // ok, because 'some-unknown-prop' is not a valid identifier
\n\nNote: If an attribute name is not a valid JS identifier (like a
\ndata-*attribute), it is not considered to be an error if it is not found in the element attributes type.
Additionally, the JSX.IntrinsicAttributes interface can be used to specify extra properties used by the JSX framework which are not generally used by the components’ props or arguments - for instance key in React. Specializing further, the generic JSX.IntrinsicClassAttributes<T> type may also be used to specify the same kind of extra attributes just for class components (and not Function Components). In this type, the generic parameter corresponds to the class instance type. In React, this is used to allow the ref attribute of type Ref<T>. Generally speaking, all of the properties on these interfaces should be optional, unless you intend that users of your JSX framework need to provide some attribute on every tag.
The spread operator also works:
\nvar props = { requiredProp: \"bar\" };\n<foo {...props} />; // ok\n\nvar badProps = {};\n<foo {...badProps} />; // error\nIn TypeScript 2.3, TS introduced type checking of children. children is a special property in an element attributes type where child JSXExpressions are taken to be inserted into the attributes.\nSimilar to how TS uses JSX.ElementAttributesProperty to determine the name of props, TS uses JSX.ElementChildrenAttribute to determine the name of children within those props.\nJSX.ElementChildrenAttribute should be declared with a single property.
\ntsdeclare namespace JSX {\n interface ElementChildrenAttribute {\n children: {}; // specify children name to use\n }\n}
\nts<div>\n <h1>Hello</h1>\n</div>;\n\n<div>\n <h1>Hello</h1>\n World\n</div>;\n\nconst CustomComp = (props) => <div>{props.children}</div>\n<CustomComp>\n <div>Hello World</div>\n {\"This is just a JS expression...\" + 1000}\n</CustomComp>
You can specify the type of children like any other attribute. This will override the default type from, eg the React typings if you use them.
\n\ntsinterface PropsType {\n children: JSX.Element\n name: string\n}\n\nclass Component extends React.Component<PropsType, {}> {\n render() {\n return (\n <h2>\n {this.props.children}\n </h2>\n )\n }\n}\n\n// OK\n<Component name=\"foo\">\n <h1>Hello World</h1>\n</Component>\n\n// Error: children is of type JSX.Element not array of JSX.Element\n<Component name=\"bar\">\n <h1>Hello World</h1>\n <h2>Hello World</h2>\n</Component>\n\n// Error: children is of type JSX.Element not array of JSX.Element or string.\n<Component name=\"baz\">\n <h1>Hello</h1>\n World\n</Component>
By default the result of a JSX expression is typed as any.\nYou can customize the type by specifying the JSX.Element interface.\nHowever, it is not possible to retrieve type information about the element, attributes or children of the JSX from this interface.\nIt is a black box.
JSX allows you to embed expressions between tags by surrounding the expressions with curly braces ({ }).
var a = <div>\n {[\"foo\", \"bar\"].map(i => <span>{i / 2}</span>)}\n</div>\nThe above code will result in an error since you cannot divide a string by a number.\nThe output, when using the preserve option, looks like:
var a = <div>\n {[\"foo\", \"bar\"].map(function (i) { return <span>{i / 2}</span>; })}\n</div>\nTo use JSX with React you should use the React typings.\nThese typings define the JSX namespace appropriately for use with React.
\nts/// <reference path=\"react.d.ts\" />\n\ninterface Props {\n foo: string;\n}\n\nclass MyComponent extends React.Component<Props, {}> {\n render() {\n return <span>{this.props.foo}</span>;\n }\n}\n\n<MyComponent foo=\"bar\" />; // ok\n<MyComponent foo={0} />; // error
The exact factory function used by the jsx: react compiler option is configurable. It may be set using either the jsxFactory command line option, or an inline @jsx comment pragma to set it on a per-file basis. For example, if you set jsxFactory to createElement, <div /> will emit as createElement(\"div\") instead of React.createElement(\"div\").
The comment pragma version may be used like so (in TypeScript 2.8):
\n\ntsimport preact = require(\"preact\");\n/* @jsx preact.h */\nconst x = <div />;
emits as:
\n\ntsconst preact = require(\"preact\");\nconst x = preact.h(\"div\", null);
The factory chosen will also affect where the JSX namespace is looked up (for type checking information) before falling back to the global one. If the factory is defined as React.createElement (the default), the compiler will check for React.JSX before checking for a global JSX. If the factory is defined as h, it will check for h.JSX before a global JSX.