SpunkArt
Data, text and encoding

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:

  1. Convert the character to its UTF-8 bytes.
  2. Write each byte as two uppercase hex digits.
  3. 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.

InputencodeURIComponentencodeURI
a b+ca%20b%2Bca%20b+c
/path with space/?q=a&b%2Fpath%20with%20space%2F%3Fq%3Da%26b/path%20with%20space/?q=a&b
café & crèmecaf%C3%A9%20%26%20cr%C3%A8mecaf%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 %20 was 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 use URLSearchParams.
  • 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.