URL encoding: how percent-escapes work
A URL may only contain a limited set of characters. Everything else, from a space to an accented letter, travels as a percent sign followed by two hex digits. Here is how those escapes are built and which encoding function fits which job.
Percent-encode or decode text
The rule behind every escape
RFC 3986, the standard that defines URL syntax, splits characters into two groups. Unreserved characters never need escaping: letters, digits, and - . _ ~. Reserved characters such as / ? # & = + : have a job inside a URL, so they must be escaped when they appear as data. Every other character, including spaces and anything outside ASCII, is always escaped.
An escape is built from bytes, not letters:
- Convert the character to its UTF-8 bytes.
- Write each byte as two uppercase hex digits.
- Put a
%in front of each pair.
Worked example. Encode the query value café & crème.
éis the UTF-8 bytes C3 A9, so it becomes%C3%A9.- The space is byte 20, so it becomes
%20. &is byte 26. Left alone, it would start a new parameter, so it becomes%26.èis C3 A8, so it becomes%C3%A8.
Result: caf%C3%A9%20%26%20cr%C3%A8me.
The euro sign takes three bytes, so € becomes %E2%82%AC. A percent sign that is data must itself be escaped: 50% off! becomes 50%25%20off!.
encodeURIComponent or encodeURI?
JavaScript has two built-in encoders, and choosing the wrong one is the most common URL bug.
| Input | encodeURIComponent | encodeURI |
|---|---|---|
a b+c | a%20b%2Bc | a%20b+c |
/path with space/?q=a&b | %2Fpath%20with%20space%2F%3Fq%3Da%26b | /path%20with%20space/?q=a&b |
café & crème | caf%C3%A9%20%26%20cr%C3%A8me | caf%C3%A9%20&%20cr%C3%A8me |
Use encodeURIComponent on one piece of a URL: a single query value or a single path segment. Use encodeURI only on a complete URL that is already correctly structured and just has stray spaces or non-ASCII letters. Neither function escapes ! ' ( ) *, which some older servers dislike.
The plus sign and spaces
HTML forms submitted with the default content type send spaces as +, not %20. That is why a literal plus inside a query value must be sent as %2B; otherwise the server reads it as a space. In JavaScript, new URLSearchParams({q: "a b&c=d"}).toString() gives q=a+b%26c%3Dd. Choose the “HTML form style” mode above to decode that kind of string.
Common mistakes
- Double encoding. If you see
%2520, a%20was encoded again. Encode raw values once, at the moment you build the URL. - Building URLs by string joining. Concatenating user input into a query string lets an
&inject a new parameter. Encode each value, or useURLSearchParams. - Decoding a lone percent sign.
decodeURIComponent("100%")throws a “URI malformed” error. The tool reports this instead of failing silently. - Using
escape(). It is deprecated and encodeséas%E9(Latin-1), not as UTF-8.
Questions
Does case matter in an escape?
No. %c3%a9 and %C3%A9 decode to the same byte. Uppercase is the recommended form.
Should I encode the domain name?
No. Domains with non-ASCII letters use a different system called Punycode. Percent-encoding is for the path, query and fragment.
Is the text I paste sent to a server?
No. The encoding runs in your browser with the built-in JavaScript functions.