HTML Decode: HTML Entities to Text

HTML decoding reads HTML character references, not percent triplets. For %20 and its kind use the URL percent-decoder.

Escape text as HTML entities →

How do you decode HTML entities back to text?

HTML decoding reads character references back as the characters they stand for, so escaped markup reads as the text somebody typed.

1. Find every ampersand. It is the only character that can open a reference.
2. Read to the semicolon. A name goes to the HTML standard's table; &# and digits are a code point in decimal, &#x and digits one in hexadecimal.
3. Write the character that reference stands for.
4. Leave an ampersand that opens nothing as an ampersand. It is text, not a mistake.
5. Read the result. A &amp; B &lt; C becomes A & B < C.

HTML Entities to Text Conversion Table

Five names are predefined and carried by both XML and HTML: &amp; for the ampersand, &lt; for the less-than sign, &gt; for the greater-than sign, &quot; for the double quote and &apos; for the apostrophe. An HTML character reference starts with an ampersand and ends with a semicolon. A named reference uses a name from the HTML standard's table (&amp;); a numeric one uses &# and decimal digits (&#65;) or &#x and hexadecimal digits (&#x41;). The last row is &nbsp; = a no-break space (code point U+00A0), which is not one of the five but is the reference you are most likely to meet.

The same value in each encoding

These rows are shared with the other encoders, so a value written here is the value every page in the family writes.

Every value below is the one the specification fixes, so a result that disagrees with a row here is a result to check.

Worked Example: A &amp; B &lt; C to Text

One character at a time, with the working written out. This is the same grid the converter shows when you turn on "show steps".

A numeric character reference can write any code point. A named one works only for a name that appears in the HTML standard's table; an ampersand followed by a name that is not in the table stays as literal text.

Read the grid a row at a time: &amp; at U+0026 becomes &; &lt; at U+003C becomes <. Every other character is left exactly as it was, which is what keeps the result readable — an escaped document is still the same text, with four or five characters standing in for one.

A is ASCII 65 = 0x41 = 0o101 = 0b01000001; a is 97 = 0x61 = 0o141 = 0b01100001. Uppercase and lowercase differ by 32, which is bit 5. The number in a numeric reference is that code point, so the decimal and the hexadecimal forms of one character are two spellings of one value rather than two different references. Counting the characters is the quickest check on the result: a reference stands for exactly one of them, however many characters it takes to write, so the text either side of it is untouched and the length of the escaped string tells you nothing about the length of the text it holds.

Check it in reverse

In HTML text only two things must be escaped: a less-than sign, and an ampersand that would otherwise start a character reference. Inside a quoted attribute value the quote character that closes it must be escaped as well. Reading it back is the same rule in reverse: an ampersand opens a reference, a semicolon closes it, and what sits between them names one character. To verify the result by hand, escape the decoded characters again and compare it with what you started from.

Worked examples: HTML entities to text

Each example gives the value first, then the working. Click a value to load it in the converter.

Every example above reverses exactly - write the same characters back as entities.

What Makes an Entity Fail to Decode?

Named reference or numeric reference?

A numeric character reference can write any code point. A named one works only for a name that appears in the HTML standard's table; an ampersand followed by a name that is not in the table stays as literal text.

Does a reference need its semicolon?

For legacy compatibility some named references appear in the HTML standard's table both with and without the closing semicolon, so a decoder may resolve a name that has no semicolon after it. This converter writes the semicolon every time, because a reference without one is only readable by luck.

What case are the hexadecimal digits?

0b marks binary, 0o octal, 0x hexadecimal; a leading # marks a hex colour. Hexadecimal is not case-sensitive (FF = ff); iToolHub writes hex digits in uppercase. A numeric reference is read the same either way.

Is this the encoding you need at all?

The three schemes protect different things and are not interchangeable. these encodings are not interchangeable - telling entities, triplets and Base64 apart sets out which does what.

HTML Entities to Text in Code

Both standard libraries carry this conversion, so the one-liner below is the whole job. Check the result against the table above before you trust it in a pipeline.

Python: html.unescape('A & B')

JavaScript: new DOMParser().parseFromString(s,'text/html').documentElement.textContent

Common Mistakes

• Escaping a value that is already escaped, which turns an ampersand into &amp;amp; and shows the reference itself on the page.
• Trusting a decoder to fix broken markup. It reads references; it does not repair tags.
• Writing a reference with no semicolon and expecting every reader to guess where it ends.
• expecting this to read %20 - percent-decoding for URLs is what handles a percent triplet.

Frequently Asked Questions

Related Conversions

• percent-encoding is a different scheme - recover the text behind a percent-encoded string instead.
• when the decoded string is a data URI, decode Base64 that holds a picture, not text.
• if the decoded value is Base64, Base64-decode a value you received next.
• to put the decoded text into a link, percent-encode text before you put it in a link.
• for a picture rather than a string, write a picture as Base64.
• to carry the decoded bytes through a text-only channel, Base64-encode a value before you send it.

The rest of the family sits on the full set of text encoding tools.