Inline Markdown to HTML

When you build HTML as a string, some characters in it are instructions to the browser, not text: < starts a tag, and & starts a character reference. A character reference is a short code that stands for one character, such as < for < and & for &; they're often called HTML entities. The browser shows the character a reference stands for as text, so < appears on the page as < but never starts a tag. HTML escaping means replacing the special characters in a piece of text with references, so the browser shows the text exactly as it was written.

It matters most when the text comes from someone else: a user's name, a comment, a search query, data from an API. Put into HTML as it is, any markup in it becomes part of your page, and markup can run JavaScript. That's called cross-site scripting (XSS): an attacker's code runs in your page with the same powers as your own, so it can read what the page shows and send requests as the signed-in user. Say a user sets their name to <img src=x onerror=alert(1)>, and the page greets them with "<p>Hello, " + name + "</p>":

A <script> element in the name would run too, when the HTML is built on the server and sent as the page. Scripts added with innerHTML don't run, which is why attacks there use event attributes such as onerror instead.

Which characters matter depends on where the text goes:

Escaping protects text in an element's content and in a quoted attribute value. Other places, such as a URL in an href or code inside a <script>, need different protection. Day to day, you often don't escape by hand: setting textContent puts text into the page as text, and React and Vue treat values you put in with {name} and {{ name }} as text, unless you opt out with dangerouslySetInnerHTML or v-html. You need escaping when you build an HTML string yourself, for innerHTML or in a server-side template.

A URL starts with a scheme, the part before the first :, which says what kind of URL it is: https: loads a page over the web, and mailto: starts an email. The javascript: scheme is different: whatever follows the colon is JavaScript code, and following the link runs it. So <a href="javascript:alert(1)">Claim your prize</a> looks like any other link, but clicking it runs alert(1) inside your page, in its origin (its scheme, host, and port, such as https://shop.example). The code gets the same powers as your own scripts: it can read what the page shows and send requests as the signed-in user. It's cross-site scripting (XSS), arriving through a URL instead of a tag.

That's a risk wherever a URL comes from someone else: the website on a user's profile, a link in a comment written in Markdown, a page to go back to after signing in. HTML escaping doesn't help. javascript:alert(1) has no <, &, ", or ' in it, so it comes out of escaping exactly as it went in, and still runs. data: URLs are another way in: they carry a whole file inside the URL, so data:text/html,<script>alert(1)</script> is an HTML page with a script in it. Chrome, Firefox, and Safari no longer let a link open one in the tab, but no link to a website needs one either.

Spotting javascript: yourself is harder than it looks, because browsers are forgiving about how a URL is written. The scheme can be in any mix of upper and lower case. Spaces and invisible control characters before it are dropped, and tabs and line breaks are removed from anywhere in the URL. In an HTML attribute, character references are decoded first, so javascript: in an href is javascript: too. new URL parses a URL the way the browser does, so it shows what the browser sees:

new URL("javascript:alert(1)").protocol;   // "javascript:"
new URL("JavaScript:alert(1)").protocol;   // "javascript:": the scheme ignores case
new URL("  javascript:alert(1)").protocol; // "javascript:": leading spaces are dropped
new URL("java\tscript:alert(1)").protocol; // "javascript:": the tab is removed
new URL("java\nscript:alert(1)").protocol; // "javascript:": and so is a line break

So don't try to list what's dangerous. That's a blocklist, and it lets through every spelling and every scheme you didn't think of. Use an allowlist instead: accept a URL only when it starts with something you know is safe, such as https://, http://, mailto:, or a relative URL starting with / or #, ignoring case. Treat anything else as unsafe, for example by showing the link's text without a link. It's a door with a guest list rather than a list of known troublemakers: a stranger in a disguise gets past the second, never the first.

Here's a blocklist that rejects URLs starting with javascript:, ignoring case, next to that allowlist:

Passing the allowlist doesn't make a URL safe to put into HTML as it is. It still goes inside an attribute value, so escape it as you would any text there. /a" onmouseover="alert(1) starts with /, so it passes, but put into href="..." as it is, its first " ends the value early, and the rest becomes an onmouseover attribute. Escaped, it's /a" onmouseover="alert(1), which stays inside the href. The browser decodes references such as & and " before it uses the URL, so escaping never breaks a link that worked.

You meet this wherever links come from users: Markdown and rich-text editors, profile pages, chat messages. React 19 replaces a javascript: URL in an href with one that only throws an error, but code that builds HTML strings, as a Markdown renderer does, or that sets element.href or location.href from data gets no such help: location.href = "javascript:alert(1)" runs the code too.