JSX Basics in MDX

JSX is what gives you React powers inside your Markdown. It looks like HTML, lives in JavaScript, and lets you drop interactive components right into your content. Once you get the basics down, mixing Markdown and JSX feels natural.

What is JSX?

JSX looks like HTML but it's actually JavaScript. React uses it to describe what the UI should look like. Under the hood, it gets compiled to function calls:

In MDX, you write JSX directly alongside Markdown. No special delimiters needed. The compiler figures out what's Markdown and what's JSX.

How JSX Works Inside MDX

Any line starting with < that looks like a valid JSX element gets treated as JSX instead of Markdown. So you can freely mix the two:

The MDX compiler handles both in a single pass.

JSX Expressions with Curly Braces

This is the big one. Curly braces {} let you embed any JavaScript expression inside JSX:

What Can Go Inside {}?

Any JavaScript expression — meaning anything that produces a value:

Important: You cannot use statements (if/else, for loops, variable declarations) inside {}. Only expressions. If you need conditional logic, use a ternary.

JSX vs HTML Differences

JSX looks like HTML but has some critical differences. These will bite you if you don't know about them.

className vs class

htmlFor vs for

Other Key Differences

Style Attribute

In JSX, style takes an object with camelCase properties — not a CSS string:

Self-Closing Tags

In HTML, elements like <img>, <br>, and <input> don't need closing tags. In JSX, every element must be closed — either with a closing tag or self-closing syntax:

Fragments

When you need to return multiple elements without adding an extra wrapper <div>, use Fragments:

Fragments are handy when you want to group JSX without adding DOM nodes:

Comments in JSX

JSX comments look different from HTML comments:

Practical Tips

<div className="tip-box">

Tip 1: Use a linter or IDE plugin that catches mistakes like class instead of className. You'll save yourself a lot of debugging.

Tip 2: JSX expressions must return a single root element. If you have siblings, wrap them in a Fragment.

Tip 3: Boolean attributes work differently. Use disabled={true} or just disabled — not disabled="disabled".

</div>

Common Pitfalls

1. Forgetting to close tags — Every tag must be closed in JSX, including <img />, <br />, <hr />
2. Using class instead of className — The most common mistake when switching from HTML to JSX
3. Putting statements in {} — Only expressions work. Use ternary operators instead of if/else
4. Missing keys in lists — When using .map(), always add a unique key prop
5. Adjacent JSX elements — Multiple elements need a Fragment or parent div wrapper

Summary

JSX in MDX is just React's component syntax mixed into your content. Remember: className not class, curly braces for expressions, close all your tags, and use Fragments when you need to group without wrapping. That's the foundation — everything else builds on these basics.