HTML encoding and URL encoding solve the same kind of problem in two different places. HTML encoding replaces characters like < and & with entities such as < and &, so a browser shows them as text instead of reading them as markup. URL encoding replaces characters with a % and two hex digits, such as %20 for a space, so they can travel safely inside a URL.
The rule of thumb: encode for the place the text is going, not for where it came from.
HTML encoding vs URL encoding at a glance
HTML encoding vs URL encoding comes down to the parser that will read the text: an HTML parser or a URL parser. Each one treats a different set of characters as special.
| HTML encoding | URL encoding | |
|---|---|---|
| Also called | Character references, HTML entities, HTML escaping | Percent-encoding |
| Used in | Page text and attribute values | Query values, path segments, form bodies |
| Format | &name;, < or < |
% plus two hex digits |
| Space becomes | Stays a space | %20, or + in form data |
& becomes |
& |
%26 |
< becomes |
< |
%3C |
| Main risk if skipped | Broken markup or cross-site scripting | Broken links or wrong parameters |
What HTML encoding does
HTML encoding swaps characters that mean something in markup for character references. An HTML character reference is an escape sequence that stands for another character in the rendered page.
All three forms render the same <:
- Named:
<, with the name between∧ - Decimal:
<, using the character's code point in base ten - Hexadecimal:
<, using the code point in hex
For output encoding, the OWASP XSS prevention rules list five conversions: & to &, < to <, > to >, " to " and ' to '. Everything else, including spaces and accented letters, can stay as it is in a UTF-8 page.
What URL encoding does
URL encoding, formally percent-encoding, replaces a character with % followed by its hex value. Percent-encoding exists because characters like /, ?, #, & and = already have jobs in a URL.
A few common ones: & becomes %26, = becomes %3D, # becomes %23, and % itself becomes %25. A space becomes %20 in a URL but + in form data sent as application/x-www-form-urlencoded.
RFC 3986 defines the format as a percent sign and two hex digits, and says producers should use uppercase hex. Letters, digits and -, ., _ and ~ are unreserved and never need encoding. In JavaScript, encodeURIComponent encodes non-ASCII characters as UTF-8 bytes, so café becomes caf%C3%A9.
One string, both encodings
Running one string through both encodings shows how little they overlap. I ran this input in Node.js:
Tom & Jerry <3 "cats"
HTML encoding:
Tom & Jerry <3 "cats"
URL encoding with encodeURIComponent:
Tom%20%26%20Jerry%20%3C3%20%22cats%22
URL encoding as form data, with URLSearchParams:
q=Tom+%26+Jerry+%3C3+%22cats%22
The HTML version keeps the spaces and touches only four characters. The URL version encodes every space as well, and the form-data version uses + instead of %20. Neither output works in the other's place: & inside a query string is just more text, and %3C on a page shows up as the literal characters.
When you need both: links with query strings
A link that carries user input needs both encodings, in a fixed order. OWASP's rule for URLs in attributes is to do URL encoding first, then HTML attribute encoding.
Say a search link needs q=Tom & Jerry and page=2:
- URL-encode the value only:
Tom%20%26%20Jerry. - Build the URL:
/search?q=Tom%20%26%20Jerry&page=2. - HTML-encode the attribute value, which turns the separator
&into&:
<a href="/search?q=Tom%20%26%20Jerry&page=2">Search</a>
The browser decodes & back to & before it follows the link, so the server receives two parameters. OWASP also warns to encode only parameter values, not the entire URL or its path. Encoding the whole URL would turn ? and / into %3F and %2F and break it.
Common mistakes and how to spot them
Most encoding bugs are one of three mistakes, and each leaves a trace you can see:
- Double URL encoding. You see
%2520where a space should be. The first pass made%20, and a second pass encoded the%as%25. - HTML encoded twice. The page literally shows
&or the source contains&amp;. Usually a template engine that escapes by default got text that was already encoded. - Wrong encoding for the context. An HTML-encoded value in a query string, or a URL-encoded string shown on a page as
Tom%20%26%20Jerry.
My take: encode at the last moment, at the exact spot where the value enters HTML or a URL, and store raw text everywhere else. Values encoded early tend to get encoded again later, and that's where %2520 comes from.
Neither encoding validates anything. OWASP points out that HTML attribute encoding doesn't validate URLs, so a javascript: link is still dangerous after encoding. For links built from user input, also allow-list http and https URLs.
To check a value by hand, paste it into an HTML entity encoder, which runs in your browser and doesn't send the text anywhere. For the JavaScript side, the difference between encodeURI and encodeURIComponent decides which characters survive, and why a plus sign decodes as a space explains the form-data quirk. If your data is going into JSON rather than HTML, escaping double quotes in JSON follows its own rules again, and Base64 vs Base64URL covers the encoding for binary data.
FAQ
Is URL encoding the same as percent-encoding?
Yes. Percent-encoding is the formal name, and it is sometimes called URL encoding. Each replaced character becomes a percent sign followed by its hex value.
Should I HTML-encode a URL before putting it in a link?
Encode the query values with URL encoding first, then HTML-encode the whole attribute value. A literal ampersand between parameters then becomes the amp entity inside the href.
Does HTML encoding protect against XSS on its own?
Only in the context it was made for. HTML encoding is right for text between tags and in quoted attributes, but it doesn't validate URLs, so links still need an allow-list of http and https schemes.
Why do I see %2520 in my URLs?
The value was URL-encoded twice. The first pass turned a space into %20, and the second pass encoded the percent sign as %25. Encode once, at the point where the value enters the URL.