React Reference ยท JSX Syntax and Rules
JSX elements
Reference for JSX elements: how a tag compiles to a call that returns a plain object, the difference between lowercase and capitalized tags, and why elements are immutable.
A JSX element is a piece of markup-looking syntax such as <h1 className="title">Hello</h1>. It is not HTML and it is not a DOM node. A build tool (Babel, SWC, esbuild, TypeScript) rewrites it into a function call that returns a small plain JavaScript object called a React element. The object describes what you want on screen: a type, its props and an optional key. React reads these descriptions and updates the DOM to match.
The first character of the tag name decides what the type is. A lowercase name (div, button, my-widget) is a string and means a built-in DOM element. A capitalized name or a dotted path (Greeting, Menu.Item) is a variable in scope, normally a function component, and the type is that function.
const element = <h1 className="title">Hello</h1>; // compiles to (automatic runtime): jsx('h1', { className: 'title', children: 'Hello' }) // or, with createElement: createElement('h1', { className: 'title' }, 'Hello')
Try it
Syntax
<tag prop="value" {...more}>children</tag> // with children <tag prop="value" /> // self-closing, no children <Component /> // capitalized: a component <Namespace.Component /> // member expression <>...</> // fragment
| Part | Description |
|---|---|
| Tag name | Lowercase: a string type naming a DOM element or custom element. Capitalized or dotted: a variable that holds a component (or a context, Fragment, Suspense and so on). |
| Attributes | Become the props object. See JSX attributes. |
| Children | Content between the tags, available as props.children. See JSX children. |
Returns: an element object with type, props and key (plus internal fields). You never construct it by hand; use JSX or createElement().
Errors: every tag must be closed (<br />, not <br>), and a JSX expression must have a single root (use a fragment to group siblings). A name that is not in scope throws a ReferenceError when the expression runs.
Usage notes
- Elements are cheap descriptions, not instances. Creating one allocates a small object. It does not render anything and does not run component code. The function runs later, when React renders it.
- Immutable. Props of an element cannot be changed; in development builds React freezes the object. To change something, create a new element, which is what each render does anyway.
cloneElement()makes a modified copy. - A capitalized name must be in scope.
<greeting />with a lowercasegis treated as an unknown DOM tag namedgreeting, and React warns in development. This is the most common beginner bug with components. - Dynamic types. To choose a tag at run time, put it in a capitalized variable:
const Tag = href ? 'a' : 'span'; return <Tag>...</Tag>. You cannot write<{expression}>. - Custom elements. Names containing a hyphen (
<my-card>) render as web components, and React 19 passes props through as properties when the element defines them. - Reuse is safe. The same element object can appear several times in the tree or be stored in a variable. Each position becomes its own instance of the component when it renders.
- JSX needs a transform. Browsers cannot run JSX. The TryIt examples compile it in the page with Babel; real projects compile it during the build. See JSX transform.
- Not a string. You cannot call
.innerHTMLor.addEventListeneron an element. To reach the real DOM node, use a ref.