Encode and decode HTML entities

An ampersand in a paragraph is fine until it is followed by something that looks like an entity name. An angle bracket in a code sample turns the rest of the page into an unclosed tag. A quote mark inside an attribute ends the attribute early.

These are the five characters that mean something to a parser, and escaping them is the whole job in one direction.

Escaping five characters, not everything

The default here escapes the ampersand, both angle brackets and both quote marks. That is the set that changes how markup is read, and escaping it is what makes arbitrary text safe to place into a document.

Escaping every non-ASCII character as well is offered and is not the default. It was standard practice when encodings were unreliable and a stray byte could render as a question mark, and there are still pipelines that expect it. The cost is that a paragraph of Greek, Japanese, Arabic or Hindi becomes an unreadable run of numeric entities that nobody can proofread, and modern documents declare UTF-8 and do not need it.

The choice is yours to make deliberately, which is why both are here and why the narrow one is the default.

Emoji and the two-halves problem

An emoji is one character to a reader and, in the way JavaScript stores text, two units. A converter that walks its input by storage unit rather than by character escapes an emoji as two separate entities, each describing half of it.

Those two halves are not valid characters on their own. Decode them and you get two replacement marks rather than the emoji, and the damage is done at the escaping step where nothing looked wrong. This walks by code point, so an emoji becomes one entity and decodes back into itself.

Decoding

Decoding accepts named entities, decimal entities and hexadecimal entities together, which is what real documents contain after passing through a few systems.

An entity that is not recognised is left exactly as it was written. That is deliberate. Guessing at what somebody meant, or dropping the text, both lose information, and a literal ampersand followed by a word is far more common in ordinary prose than a misspelled entity.

The decoder is the one this site already uses for converting HTML into other formats, which had to be fixed once after a crafted entity name read a property off the object prototype and returned a function where text was expected. A second decoder written here would have been a second chance to make that mistake.

Everything runs in this browser tab, and nothing is sent anywhere.