HTML entity encoder / decoder

What this tool does

HTML has no way to tell the difference between a less-than sign you meant as text and one that opens a tag. The language solves this with entities: short escape sequences that stand for a character without being read as markup. This tool converts in both directions — plain text into its escaped form, and escaped HTML back into the characters it stands for.

Both directions run entirely in your browser. That matters more here than for most tools, because the text people paste into an entity decoder is usually a scraped page, a customer email or a database column someone is trying to make sense of.

The five characters that matter

Thousands of entities exist, but only a handful are needed to make text safe. Encoding here replaces exactly five characters and leaves everything else readable:

• The ampersand becomes & — this one first, or every other replacement would itself be re-read as an entity.
• The less-than sign becomes < — the character that can start a tag.
• The greater-than sign becomes > — less dangerous on its own, escaped for symmetry and to survive careless parsers.
• The double quote becomes " — needed inside attribute values written with double quotes.
• The apostrophe becomes ' — needed inside attribute values written with single quotes.

That last one is written numerically on purpose. There is a name for it, ', but it comes from XML and HTML 4 never defined it, so old parsers pass it through as literal text and the escaping quietly fails. The numeric form has always worked everywhere, which is why serious escaping libraries emit it.

Named, decimal and hexadecimal

Any character can be written three ways, and decoding accepts all of them. The em dash is a good example:

named     —      the readable form, but only for characters that have a name
decimal   —      the code point in base 10
hex       —     the same code point in base 16, the notation Unicode charts use

This tool recognises the 255 names of the HTML 4 set when decoding — the Latin-1 letters, the Greek alphabet, the arrows, the mathematical symbols and the typographic punctuation, which between them cover essentially everything that turns up in real text. HTML 5 defines around 2200 more, almost all obscure mathematical symbols; carrying that table would add tens of kilobytes to every page load in exchange for names most documents never use. A name outside the set is reported rather than dropped, so the cost is a warning, never a wrong answer.

Encoding goes the other way and stays deliberately plain: names for the five characters above, decimal numbers for everything else. Nothing is turned into … or ’ when the character itself is perfectly valid in a UTF-8 document.

Escaping is not one rule but four

It is tempting to treat entity escaping as the answer to injection, and inside element content it genuinely is. But HTML is really four languages nested in each other, and each has its own rules. Entity escaping is correct in the first two of these places and useless in the rest:

• Element content — text between tags. Entity escaping is exactly right.
• Quoted attribute values. Entity escaping is right, provided the attribute really is quoted; without quotes a space in the value ends the attribute and the escaping buys you nothing.
• Inside a script block. JavaScript string escaping applies, not entities — the browser does not decode entities there, so an escaped quote arrives as the literal characters ".
• URL attributes such as href and src. Entity escaping does not stop a javascript: URL, because the danger is in the scheme, not in any character an entity would replace.

The practical rule: escape at the point where text is inserted into a document, using the rules of the exact context it lands in — not once, early, in the hope that it will hold everywhere later.

Why you sometimes see &

This is the single most common reason to reach for an entity decoder. Text was escaped, then escaped again — usually once by application code and once by a template engine or framework that already escapes its output:

original     Fish & Chips
escaped      Fish & Chips        renders as: Fish & Chips
escaped x2   Fish & Chips    renders as: Fish & Chips

Decoding removes exactly one layer, so running it once tells you which case you are in. If the output still contains entities, there was more than one layer. The fix is almost never to strip entities at display time — it is to find and remove the duplicate escaping step, because the same bug is silently corrupting stored data.

Non-ASCII, and the option for it

A page served as UTF-8 needs no entities for accented letters, Hebrew, Arabic, Chinese or emoji. Those characters are valid as they are, and leaving them readable keeps the source legible and the file smaller. That is the default here.

The option exists because some destinations still insist on plain ASCII: older email templates, systems that mangle bytes above 127, or a database column whose encoding nobody is willing to change. Turning it on writes every such character as a decimal reference — é becomes é, א becomes א.

Emoji are worth a note. An emoji is written as one reference for its whole code point, for example 🙂, never as two halves. If you have used the JSON escape tool this is the opposite of what happens there, where the format specifically requires an emoji to be split into two \u escapes. Same character, two correct answers, because the two formats define escaping over different units.

When a reference cannot be decoded

Decoding here never fails and never deletes anything. A reference that cannot be resolved is left exactly as it was found and listed above the output with its line and column. Three things get reported:

• An unknown name, such as &nbps; — nearly always a typo for  . This is the warning worth acting on: it means a space is missing from your content and nobody noticed.
• A number that is not a character, such as � or a value above the Unicode range. There is nothing to decode it to, so it stays as text.
• A number between 128 and 159. See below.

A lone ampersand is not reported at all. In HTML, R&D and Q&A are ordinary text, and treating every stray ampersand as an error would bury the warnings that matter under noise from prose.

The 128-to-159 range is a genuine oddity. Those numbers name invisible control characters that nobody ever means to write; they appear because a document was authored in Windows-1252, where the same numbers are curly quotes, dashes and the euro sign. Browsers quietly read them as Windows-1252 for exactly that reason, and this tool matches that behaviour so the result equals what a page would actually display — but it says so in the warnings, because a silent substitution you did not ask for is worse than a noisy one.