How percent-encoding works
A URL may only contain a small set of ASCII characters, and some of those have jobs: “/” separates path segments, “?” starts the query, “&” separates parameters, “=” joins a name to its value and “#” starts the fragment. Percent-encoding, defined in RFC 3986, lets any other character, or a reserved character used as plain data, travel safely.
character → UTF-8 bytes → %HH for each byte
The character is first converted to bytes with UTF-8. Each byte is then written as a percent sign followed by two hexadecimal digits, H, from 00 to FF. Letters, digits and a few marks are left alone. Decoding reverses the steps: every %HH becomes a byte and the bytes are read as UTF-8.
Whole URL, one component, or form data
| Choice | Left unencoded | Space |
|---|---|---|
One component (JavaScript encodeURIComponent) | A–Z a–z 0–9 - _ . ! ~ * ' ( ) | %20 |
| Strict RFC 3986 component | A–Z a–z 0–9 - _ . ~ | %20 |
A whole URL (encodeURI) | the above plus ; , / ? : @ & = + $ # | %20 |
Form data (WHATWG URL Standard, application/x-www-form-urlencoded) | A–Z a–z 0–9 * - . _ | + |
Use one component for a value you are inserting into a URL, such as a search term, a file name or a query parameter value. Use a whole URL to tidy an address that is already put together, because it leaves the separators working. Use form data for a query string built the way an HTML form submits it, where spaces become “+”.
Worked example: “café & crème”
- Plain letters stay. c, a, f, c, r, m and e are unreserved and pass through.
- Accented letters become UTF-8 bytes. é is the two bytes C3 A9, giving
%C3%A9; è is C3 A8, giving%C3%A8. - The space is 20 in hexadecimal (32 in decimal), giving
%20. - The ampersand is 26, giving
%26, so it can no longer be mistaken for a parameter separator. - Result as a component:
caf%C3%A9%20%26%20cr%C3%A8me. As form data:caf%C3%A9+%26+cr%C3%A8me. As a whole URL the “&” is left alone:caf%C3%A9%20&%20cr%C3%A8me.
The choice matters. Encoding https://example.com/a b?q=1&r=é as a whole URL gives https://example.com/a%20b?q=1&r=%C3%A9, still a working address. Encoding it as a component gives https%3A%2F%2Fexample.com%2Fa%20b%3Fq%3D1%26r%3D%C3%A9, which is right only if the whole address is being passed as a value inside another URL.
Common mistakes
Encoding twice. Encoding text that is already encoded turns each “%” into %25, so a space becomes %2520. If you see %25 followed by two hex digits, the text has probably been encoded twice; decode it once.
“+” is only a space in form data. In a path or in strict component encoding, “+” is a literal plus sign. Decoding an ordinary URL in form mode will wrongly turn plus signs into spaces, and phone numbers such as +61 lose their plus.
Decoding a whole URL keeps reserved escapes. In whole-URL mode, escapes for ; / ? : @ & = + $ , and # are left as they are, as decodeURI does, because decoding %2F to “/” or %3F to “?” would change the meaning of the address. Use component mode to decode everything.
Malformed sequences. A “%” must be followed by two hexadecimal digits, so “100%” on its own cannot be decoded; encode the percent sign as %25. A sequence such as %E9 on its own is not valid UTF-8: it is “é” encoded with the older Latin-1 character set. The calculator stops and names the position of the first problem.