HTML Entities: Encode and Decode Without Breaking Markup

An HTML entity is a short sequence that represents a character the parser would otherwise treat as markup. The ampersand starts an entity, the less-than sign starts a tag, and a quote can end an attribute. Encode the wrong one and a page shows raw code; encode twice and visitors see & in the middle of a sentence. This guide covers the rules, the exact behavior of the local HTML entities tool, and the contexts where HTML escaping is the wrong layer entirely.

Part of the developer toolkit guide. The tool handles text-level escaping in the page. It is not a template engine, a URL encoder or a JavaScript string escaper, and it does not know where the result will be inserted.

When escaping matters

In HTML text content, two characters are mandatory: & becomes & and < becomes <. The greater-than sign does not have to be escaped in text, but escaping it avoids confusion around sequences such as ]]>. In an attribute value, the quote that delimits the attribute must also be escaped. A double-quoted attribute needs "; a single-quoted attribute needs ' or '.

That distinction explains a common mistake. People paste text containing " and ' into an HTML encoder, see the quotes unchanged, and assume the tool is broken. It is not. In a text node, quotes need no escaping at all. The encoder is doing exactly what the browser's serializer does for text. If you are building an attribute string by hand, you need a different step that knows the delimiter.

There are also contexts where HTML entities do nothing useful. Inside a URL query value, a space must be percent-encoded, not turned into  . Inside a JavaScript string, a quote needs a backslash, not an entity, unless the string is itself inside an HTML attribute and the whole thing is decoded before the script runs. Inside JSON, entities are just text and should not be introduced. Match the escaping to the parser that will read the value next.

What the encoder and decoder actually do

Encode reads the input as text and serializes it back as HTML. In practice that means &, < and > are escaped, a non-breaking space becomes  , and ordinary punctuation and accented letters stay as they are. Quotes are not escaped because they are not special in a text node. The tool accepts up to 1,000,000 characters and reports an error above that limit.

Decode does the reverse: it parses the input as HTML fragment content and returns the text value. Named entities such as ©, decimal references such as © and hexadecimal references such as © all become the corresponding character. An unknown entity such as &unknown; is left as literal text by the browser rather than causing an error, so a successful decode does not prove that every entity was valid.

Neither direction is a sanitizer. Encoding makes text safe for display, but decoding an untrusted string and inserting the result with innerHTML would reintroduce markup. The tool returns text; where you put it is still your responsibility. Use textContent for plain text insertion, and a maintained sanitizer if you genuinely need to allow a subset of HTML.

Named, decimal and hexadecimal references

Named entities are easier to read, numeric references are more predictable across old documents.   is U+00A0, a non-breaking space that prevents a line break but is not an ordinary space for searching or wrapping. Replacing every space with it produces text that cannot wrap naturally. © is ©, — is an em dash, and ’ is a right single quotation mark. HTML5 recognizes a large set of names; XML without a DTD recognizes only a handful, which is why numeric references are safer in XML.

Names are case-sensitive. & and & both decode to an ampersand, but &Amp; is not recognized, and a missing semicolon can change how the parser consumes the following characters. Browsers are lenient with some legacy forms, but email clients and XML parsers are not. Always include the semicolon and prefer lowercase names from the HTML standard.

Hexadecimal references are useful for characters you cannot easily type. 😀 is a grinning face emoji, and ' is an apostrophe. Supplementary-plane characters can also be written as surrogate pairs, but a single code point reference is cleaner. Keep the x lowercase or uppercase consistently; both parse, but a style checker will thank you.

The attribute problem

Suppose you have a title and want to place it in title="...". If the title contains a double quote, the encoder leaves it alone because it treats the input as text. The attribute then ends early and the rest of the title becomes stray attributes. The correct workflow is to replace & first, then the delimiter quote, then the less-than sign if your framework requires it. Order matters: replacing & last would double-escape the ampersands introduced by the other replacements.

If you control the template, let the framework do this work. React, Vue, Svelte and server-side template engines escape interpolated values according to context. Raw HTML helpers exist precisely because escaping is context-sensitive. Hand-encoding a string and then passing it to a helper that escapes again is how visible entities end up on the page.

The same warning applies to URLs. An ampersand separating query parameters must become & in an HTML attribute, but the parameter values themselves need percent-encoding before that. Two layers, two encoders. The URL encoding guide covers the percent-encoding layer; this tool covers the HTML layer.

Recognizing double escaping

If a page displays &, the source probably contains & or the value was encoded twice. If it displays <div> where a tag was intended, the content was encoded for display and then inserted as markup, or encoded before a template escaped it again. Decode once in a scratch copy and compare with the source of truth. Do not decode directly in a production database or CMS field unless you have a backup.

Round-tripping is a useful test. Encode a sample, decode the result, and compare it with the original. For plain text without non-breaking spaces, the result should match. If it does not, look for a second encoding step, a sanitizer that rewrote entities, or a rich-text editor that normalized the markup on save.

Email templates are a frequent offender. A marketing platform may escape merge tags, then an email client may decode them differently. Test the final received message, not just the preview in the editor. Transactional email should keep entities simple and avoid relying on named entities that older clients might not recognize.

A safe encode or decode checklist

1. Identify the destination context: text node, attribute, URL, script or JSON.
2. Use this tool only for HTML text. Use percent-encoding for URLs and a language-specific escaper for scripts.
3. Encode a copy and paste the result into the smallest possible test page.
4. Check quotes, ampersands and non-breaking spaces specifically; they are the usual suspects.
5. Decode a sample back and compare it with the original before saving.
6. Let the template engine handle dynamic values instead of pre-encoding them.