Writing markup with JSX

HTML that doesn't paste

In Your first component, every component returned markup that looked like HTML. That markup is JSX. It looks so much like HTML that the first thing people try is pasting HTML into a component. Here is a sign-up box for a tea shop, as plain HTML. Its result is live:

1<h2>Join the tea club</h2>2<p class="hint">One email a month.<br>New teas first.</p>3<label for="email">Email</label>4<input id="email" type="email">5<button>Join</button>

Five lines: a heading, a hint with a line break, a label, an email box, and a button. Now the same five lines, pasted into a component as they are:

1export default function JoinBox() {2  return (3    <h2>Join the tea club</h2>4    <p class="hint">One email a month.<br>New teas first.</p>5    <label for="email">Email</label>6    <input id="email" type="email">7    <button>Join</button>8  );9}

Nothing shows. The result is a syntax error on line 4: Unexpected token, expected ",". The message is puzzling, because the compiler is confused: line 3 is already a whole tag, and in JavaScript nothing can follow it inside the brackets of a return. That's one of four things to fix. Here is the box as JSX:

1export default function JoinBox() {2  return (3    <section className="join-box">4      <h2>Join the tea club</h2>5      <p className="hint">One email a month.<br />New teas first.</p>6      <label htmlFor="email">Email</label>7      <input id="email" type="email" />8      <button>Join</button>9    </section>10  );11}

1. One root. A <section> on line 3 holds everything, and closes on line 9.
2. Closed tags. <br> became <br /> on line 5, and the <input> on line 7 ends with />.
3. className in place of class, on lines 3 and 5.
4. htmlFor in place of for, on line 6. Click the word Email in the result: the cursor jumps into the box, because htmlFor links the label to the input with the id email.

These rules aren't a list to memorize. They all come from one fact: before your code runs, every JSX tag becomes a JavaScript function call.

Every tag becomes a function call

Browsers don't understand JSX. A compiler, a tool that rewrites code, turns it into plain JavaScript first: Babel, TypeScript, esbuild, or Sucrase, usually run for you by your build tool. Every live example on this site is compiled by Sucrase, in your browser, a moment before it runs. Here is a small card:

1export default function TeaCard() {2  return (3    <article className="tea-card">4      <h3>Green tea</h3>5      <p>$3</p>6    </article>7  );8}

And here is what a compiler really turns it into. This is the output of TypeScript's compiler with the setting jsx: "react-jsx", React's modern JSX transform, formatted with Prettier. Babel and Sucrase write the same calls; the lesson's tests compile the card with all three and compare.

import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
export default function TeaCard() {
  return _jsxs("article", {
    className: "tea-card",
    children: [
      _jsx("h3", { children: "Green tea" }),
      _jsx("p", { children: "$3" }),
    ],
  });
}

Read it line by line:

1. Line 1 imports two functions, jsx and jsxs, from react/jsx-runtime, a part of the react package made for compilers. The compiler added this line; you never write it.
2. Line 3: the <article> tag became a call. Its first argument is the type, the tag's name as a string, "article".
3. Lines 3 to 9: its second argument is one object, the props. The attribute became a key on line 4, className: "tea-card", and the tags inside became children (lines 5 to 8).
4. Lines 6 and 7: each child is its own call, with its text as children. A tag with one child uses jsx; the article, with two children in an array, uses jsxs. They build the same thing.

A capitalized tag works the same way, with one difference you met in the last lesson: <TeaCard /> becomes jsx(TeaCard, {}), with your function itself as the type, not a string.

So what does a jsx() call give back? An element: a plain JavaScript object that describes the tag, as you saw in How React works. Now you know where it comes from. This example stores one in a constant and prints two of its fields. Press Edit & run if the console isn't showing:

1const title = <h3 className="title">Green tea</h3>;2 3console.log(title.type);4console.log(title.props);5 6export default function App() {7  return title;8}

Line 1 makes the element; nothing is on the page yet. Line 3 prints its type, h3, and line 4 its props: an object with className: "title" and children: "Green tea". Line 7 returns that same object, and React turns it into the real <h3> you see. An element is only a description; React reads it to decide what to put on the page. (It has a few more fields, like key and a hidden tag that marks it as a React element. React elements and the JSX runtime, in the course's last stage, looks at every one.)

Older React code compiled JSX differently. The classic transform turned every tag into React.createElement(type, props, ...children). Here is the same card compiled the classic way (TypeScript with jsx: "react"), from a file that started with import React from "react":

import React from "react";
export default function TeaCard() {
  return React.createElement(
    "article",
    { className: "tea-card" },
    React.createElement("h3", null, "Green tea"),
    React.createElement("p", null, "$3"),
  );
}

The calls on lines 3, 6, and 7 name React, so every file with JSX had to import React (line 1), even when it used nothing else from it. The children are extra arguments (lines 6 and 7), and a tag without attributes gets null. React 17, in 2020, introduced the modern transform, which imports jsx itself. The React 19 upgrade guide made it required: React 19 uses it for features like passing ref as a prop, and in development it warns when an app still uses the classic one.

How to read this table: each row asks the same question of both transforms.

createElement itself isn't gone. It's still the way to build elements by hand, without JSX, and it builds the same elements. This card has no JSX at all, and looks exactly like the one above:

1import { createElement } from "react";2 3export default function TeaCard() {4  return createElement(5    "article",6    { className: "tea-card" },7    createElement("h3", null, "Green tea"),8    createElement("p", null, "$3"),9  );10}

Line 1 imports createElement by name. Lines 4 to 9 are three calls: the article, with its props on line 6, and its two children on lines 7 and 8. JSX is a shorter way to write calls like these; you can always do without it, and nobody does, because the markup is much easier to read.

Now compile your own. Pick an example or type any JSX in the box, and switch between the two transforms. The two last examples show the compiler stopping: the next two sections explain why.

One root, because a function returns one value

Here are two tags side by side in a component's return:

1export default function TeaCard() {2  return (3    <h3>Green tea</h3>4    <p>$3</p>5  );6}

The compiler stops on line 4. Picture what it would have to write: each tag is a call, so the return would hold two calls side by side:

return (
  _jsx("h3", { children: "Green tea" })
  _jsx("p", { children: "$3" })
);

Lines 2 and 3 are two values with nothing joining them, and a return gives back exactly one value. There's no JavaScript to write, so the compiler gives up. Different compilers say it differently. Sucrase, in these live examples, says Unterminated regular expression: once the <h3> has ended, it reads the next < as "less than", then tries to read /p> as a regular expression, and gets lost. Babel says it plainly: Adjacent JSX elements must be wrapped in an enclosing tag. Did you want a JSX fragment <>...</>?, and TypeScript says JSX expressions must have one parent element.

The fix is one parent around both. A <div> works, and adds a <div> to the page:

1export default function TeaCard() {2  return (3    <div>4      <h3>Green tea</h3>5      <p>$3</p>6    </div>7  );8}

Lines 3 and 6 open and close the <div>. When you don't want an extra element, for example inside a list or a table where a <div> doesn't belong, use a Fragment: an empty tag, <> and </>.

1export default function TeaCard() {2  return (3    <>4      <h3>Green tea</h3>5      <p>$3</p>6    </>7  );8}

The result looks the same, but the page holds only the <h3> and the <p>. Here is what the Fragment compiles to:

import {
  jsx as _jsx,
  Fragment as _Fragment,
  jsxs as _jsxs,
} from "react/jsx-runtime";
export default function TeaCard() {
  return _jsxs(_Fragment, {
    children: [
      _jsx("h3", { children: "Green tea" }),
      _jsx("p", { children: "$3" }),
    ],
  });
}

Line 3 imports Fragment along with jsx and jsxs. Lines 7 to 12 are one call, with React's Fragment as the type and both tags in children: one value for the return. When React meets a Fragment, it puts the children on the page and nothing for the Fragment itself. The long form, <Fragment>…</Fragment> with Fragment imported from react, does the same and can take a key, which the Rendering lists lesson uses.

Every tag must be closed

HTML lets some tags stay open. <br>, <input>, and <img> never have children, and the browser's HTML reader knows each of them by name. It even closes a <li> or a <p> for you when the next one starts. JSX doesn't:

1export default function SignUp() {2  return (3    <form>4      <input type="email">5      <button>Join</button>6    </form>7  );8}

The <input> on line 4 is never closed, so the compiler takes everything after it as its children: the <button> on line 5, and then </form> on line 6, which doesn't match. Sucrase stops there with Unterminated JSX contents; TypeScript names the real culprit, JSX element 'input' has no corresponding closing tag.

Why so strict? A tag's children go into its call's children, so the compiler must know where they end. And a JSX compiler knows no tag names: <input> and <TeaCard> look alike to it, and either could have children. So you say where every tag ends. A tag with children gets its closing tag, and a tag without children closes itself with />:

1export default function SignUp() {2  return (3    <form>4      <p>One email a month.<br />New teas first.</p>5      <input type="email" />6      <hr />7      <button>Join</button>8    </form>9  );10}

Line 4 closes the line break as <br />, line 5 the email box, and line 6 a horizontal rule, <hr />. Any tag may close itself when it has no children, which is why you write components as <TeaCard />. Press Edit & run and remove the / on line 6: the result turns into an error, and comes back when you put it back.

Attributes become object keys

You saw className="tea-card" become { className: "tea-card" } in the compiled card. Every attribute becomes a key in the props object, and React DOM uses each key to set the matching DOM property on the real element, the way you would in plain JavaScript with element.className = "tea-card" (the Modifying the DOM lesson covers DOM properties). That's where JSX's attribute names come from: they're the DOM properties' names.

1export default function SignUp() {2  return (3    <form className="join-box">4      <label htmlFor="email">Email</label>5      <input6        id="email"7        type="email"8        autoComplete="email"9        maxLength="40"10        aria-describedby="email-hint"11      />12      <p id="email-hint" className="hint">One email a month.</p>13    </form>14  );15}

Line by line:

• Line 3: className, because the DOM property for class is element.className. The DOM chose that name because class is a reserved word in JavaScript.
• Line 4: htmlFor, the DOM property for for, which is a reserved word too. Click Email in the result to see it link the label to the box.
• Lines 8 and 9: multi-word attributes are camelCase, like their DOM properties: autoComplete and maxLength. So are tabIndex, and SVG's strokeWidth for stroke-width. Event props like onClick are camelCase too; Responding to events covers them.
• Line 10: aria-describedby keeps its dashes. aria-* and data-* attributes are written exactly as in HTML.

There's a JavaScript reason too. You'll often take props out with destructuring, and that makes each name a variable. const { className } = props works, but const { class } = props is a SyntaxError, and a name with a dash, like stroke-width, can't be a variable at all.

What if you write HTML's names anyway? Here the form uses class, for, and tabindex:

1export default function SignUp() {2  return (3    <form class="join-box">4      <label for="email">Email</label>5      <input id="email" type="email" tabindex="0" />6    </form>7  );8}

The page still looks right: React passes the unknown names to the page as attributes. But press Edit & run and read the console. React warns once for each of lines 3 to 5, and names the fix, as in Invalid DOM property `class`. Did you mean `className`? Treat these warnings as bugs. Pick an attribute below to see how JSX spells it, with live checks of why:

Turning real HTML into JSX

You'll often start from HTML: a design someone handed you, an old page, a snippet from documentation. Here are a tea shop's opening hours and a visit form, with every kind of difference in it:

1<!-- The shop's opening hours -->2<h2 class="title">Opening hours</h2>3<p>Monday to Friday: 8 to 6<br>Saturday: 9 to 4</p>4<label for="visit">Plan a visit</label>5<input id="visit" type="date">6<label for="name">Your name</label>7<input id="name" maxlength="20">

Turn it into JSX with five checks, in this order:

1. Wrap it all in one root. Here, a Fragment, <>…</>, since the page doesn't need another element.
2. Close every tag: the <br> on line 3 and both inputs.
3. Rename class (line 2) to className and each for (lines 4 and 6) to htmlFor.
4. Write other multi-word attributes in camelCase: maxlength on line 7 becomes maxLength.
5. Turn the HTML comment on line 1 into a JavaScript comment inside braces, {/* … */}. JSX has no <!-- -->; the braces, which the next lesson is about, let you put JavaScript, and its comments, in markup.

1export default function OpeningHours() {2  return (3    <>4      {/* The shop's opening hours */}5      <h2 className="title">Opening hours</h2>6      <p>Monday to Friday: 8 to 6<br />Saturday: 9 to 4</p>7      <label htmlFor="visit">Plan a visit</label>8      <input id="visit" type="date" />9      <label htmlFor="name">Your name</label>10      <input id="name" maxLength="20" />11    </>12  );13}

Line 3 opens the Fragment and line 11 closes it. Lines 4 to 10 are the HTML's seven lines, each fixed. Line 4 is the comment, which never reaches the page. The two results look the same. For a long page, an HTML-to-JSX converter does these steps for you; it still helps to know what it changes and why. One more HTML habit, a style="…" attribute, needs an object in JSX; the next lesson covers it.

How to read this table: each row is an HTML habit, how JSX writes it, and why.

Common mix-ups

• "JSX is HTML inside JavaScript." No. It looks like HTML, but each tag becomes a function call that returns a plain object. That's why its rules are JavaScript's.
• "The browser runs my JSX." No. A compiler turns it into JavaScript first: your build tool in a project, or Sucrase in this site's live examples.
• "JSX only works with React." No. JSX is a syntax; React is a library. Other libraries use JSX with their own jsx functions, and React works without JSX, through createElement.
• "A Fragment adds a wrapper element." No. <>…</> groups tags into one value and leaves nothing on the page.
• "className is a React invention." No. It's the name of the DOM property, element.className, which existed long before React.
• "Every attribute is camelCase in JSX." Almost. aria-* and data-* keep their dashes.
• "Every file with JSX needs import React." Not since the modern transform: the compiler imports jsx from react/jsx-runtime itself.

Practice exercises

Each exercise shows its code's result under it, or when you press Edit & run. When the result is an error, read its line number first. Try a guess, then use the hints.

const menu = (
  <ul className="menu">
    <li>Green tea</li>
    <li>Mint tea</li>
    <li>Lemon cake</li>
  </ul>
);

import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
const menu = _jsxs("ul", {
  className: "menu",
  children: [
    _jsx("li", { children: "Green tea" }),
    _jsx("li", { children: "Mint tea" }),
    _jsx("li", { children: "Lemon cake" }),
  ],
});

export default function SignUp() {
  return (
    <form>
      <p>One email a month.<br>New teas first.</p>
      <input type="email">
      <button>Join</button>
    </form>
  );
}

1export default function SignUp() {2  return (3    <form>4      <p>One email a month.<br />New teas first.</p>5      <input type="email" />6      <button>Join</button>7    </form>8  );9}

export default function CakeCard() {
  return (
    <h3>Lemon cake</h3>
    <p>$4</p>
  );
}

1export default function CakeCard() {2  return (3    <>4      <h3>Lemon cake</h3>5      <p>$4</p>6    </>7  );8}

1export default function Feedback() {2  return (3    <form class="join-box">4      <label for="note">Tell us what you think</label>5      <textarea id="note" maxlength="200" tabindex="0" />6      <button>Send</button>7    </form>8  );9}

1export default function Feedback() {2  return (3    <form className="join-box">4      <label htmlFor="note">Tell us what you think</label>5      <textarea id="note" maxLength="200" tabIndex="0" />6      <button>Send</button>7    </form>8  );9}

<!-- Today's special -->
<h3 class="special">Today's special</h3>
<p>Jasmine tea<br>$5 a pot</p>
<label for="cups">Cups</label>
<input id="cups" type="number" maxlength="2">

1export default function TodaysSpecial() {2  // Turn the HTML above into JSX, and return it here3  return null;4}

1export default function TodaysSpecial() {2  return (3    <>4      {/* Today's special */}5      <h3 className="special">Today's special</h3>6      <p>Jasmine tea<br />$5 a pot</p>7      <label htmlFor="cups">Cups</label>8      <input id="cups" type="number" maxLength="2" />9    </>10  );11}

1import { createElement } from "react";2 3export default function Menu() {4  return createElement(5    "ul",6    null,7    createElement("li", null, "Green tea"),8  );9}

1import { createElement } from "react";2 3export default function Menu() {4  return createElement(5    "ul",6    null,7    createElement("li", null, "Green tea"),8    createElement("li", null, "Mint tea"),9  );10}

Check your understanding

Picture each tag as its jsx() call: most answers follow from it. Press Edit & run on a question's code to check your answer.

Key takeaways

• JSX is markup inside JavaScript. A compiler turns each tag into a jsx() or jsxs() call from react/jsx-runtime, which returns an element: a plain object with a type and props.
• The classic transform wrote React.createElement and needed import React. React 19 needs the modern one; createElement stays for building elements by hand.
• A component returns one root, because a function returns one value. Use a Fragment, <>…</>, to add none.
• Close every tag, <br /> and <input /> too: the compiler must know where children end.
• Attributes become props keys named like DOM properties: className, htmlFor, camelCase. Only aria-* and data-* keep their dashes.

Coming next: JavaScript in JSX with curly braces. It shows how to put values, expressions, and objects like style inside your markup.