HTML Entities Guide

What is an HTML entity?

An entity is text that stands for one character. It starts with an ampersand and ends with a semicolon. There are three forms:

• Named: © is ©.
• Decimal: © is ©, using the Unicode code point in decimal.
• Hex: © is ©, using the code point in hex.

Why entities exist

1. Reserved characters. The characters < and & have a meaning in HTML. To show them you must write < and &.
2. Hard to type or ambiguous characters. Entities let you write a non-breaking space or a typographic dash in a way you can see in the source.
3. Old character sets. Before UTF-8 was common, entities were the safe way to include any character outside plain ASCII.

The ones you really need

• Always encode & and < in text.
• Inside attribute values, also encode the quote character you use around the value.
• With a UTF-8 page and <meta charset="utf-8">, type é, €, © and emoji directly. You do not need entities for them.

The non-breaking space

  keeps two words together on one line and is not collapsed with the spaces next to it. It is right for a number and its unit, such as 10 kg. It is the wrong tool for layout: use margins and padding for spacing. A page full of nbsp is hard to edit, and the invisible character often causes trouble when text is copied into a database or a spreadsheet.

Why text shows &amp; on a page

Double encoding. The text was encoded when it was saved and again when it was shown, so < became < and the browser displays < as text. The fix is to encode once, at the last step, when you write the text into the page. Never store already encoded text unless you have to. If you inherit double-encoded data, the HTML decoder with repeat turned on cleans it.

Ampersands in URLs

In an HTML attribute, a link such as ?a=1&b=2 should be written ?a=1&b=2, because a bare ampersand followed by letters can be read as an entity. Browsers forgive many cases, and the validator does not.

Security: encode for the right place

Encoding user text with HTML entities protects text and quoted attribute values from cross-site scripting. It does not protect other places:

• Inside a <script> block, use JSON encoding, not HTML entities.
• Inside a URL, use percent-encoding.
• Inside CSS, use CSS escapes.
• Never put untrusted text into an unquoted attribute, a tag name or an event handler.

Always encode when you output, and use your framework's escaping, since it handles these cases for you.

Encode and decode in code

// PHP
$safe = htmlspecialchars($text, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8');
$text = html_entity_decode($safe, ENT_QUOTES | ENT_HTML5, 'UTF-8');

# Python
import html
safe = html.escape(text)
text = html.unescape(safe)

// JavaScript, in a browser: decode
const box = document.createElement('textarea');
box.innerHTML = safe;
const text = box.value;

// JavaScript, in a browser: encode &, < and >
const div = document.createElement('div');
div.textContent = text;
const safe = div.innerHTML;

In Node.js, the he package does both. Note that the JavaScript encoding trick leaves quotes unchanged, so it is for text content and not for attribute values.

Entities in XML and JSON

XML defines only five entities: <, >, &, " and '. Others, such as  , are errors in XML unless declared, and you should use the numeric form. JSON does not use entities, and its escape for a character is \u20AC. The entity converter produces both.

Common problems

• A missing semicolon. Browsers accept a few entities without it, but not most, and the result depends on the text that follows.
• An entity name in the wrong case. Names are case sensitive: É is É and é is é.
• Numeric codes 128 to 159. Browsers read them as Windows-1252 characters, so – is an en dash. Use the real Unicode code instead.
• Mojibake such as € for €. The file and the page are using different character sets. Save and serve everything as UTF-8.

More tools

Look up names in the HTML entities list, tidy markup with the HTML formatter, and clean up text with find and replace.