Percent-encoding

How it works

A URL can contain only a limited set of characters, and some of those characters have jobs: / separates path segments, ? starts the query, & separates parameters, = joins a key to its value and # starts the fragment. To put any other character in a URL, or to use one of those characters as plain data, you replace each byte with % and two hex digits.

• A space is byte 0x20, so it becomes %20.
• An ampersand inside a value is 0x26, so it becomes %26. Without that, it would split the parameter in two.
• Non-ASCII characters are first converted to UTF-8, then each byte is encoded: é is the two bytes C3 A9, so it becomes %C3%A9, and ☃ becomes %E2%98%83.

Letters, digits and - . _ ~ are the unreserved characters and never need encoding.

Which characters to encode depends on where they go

The same text needs different treatment in different places, which is why JavaScript has two built-in functions:

Function	Use for	Encodes / ? & = #
encodeURIComponent	A single value inside a URL	Yes
encodeURI	A whole URL that has spaces or accents in it	No

HTML forms use a variant, application/x-www-form-urlencoded, where a space becomes + instead of %20.

Common pitfalls

• Using the wrong function. encodeURI on a value leaves & and = alone, so a value containing them corrupts the query.
• Double encoding. Encoding text that is already encoded turns %20 into %2520. It usually means both your code and a library encoded the same value.
• + versus %20. A plus sign means “space” only in form-encoded data. In a path it is a literal plus.
• Decoding too early. Decode a URL’s parts only after splitting it. If you decode %2F or %26 first, it turns into / or & and changes the URL’s structure.
• Legacy encodings. Some old systems encode in Latin-1, where é is a lone %E9. That is not valid UTF-8, so a strict decoder rejects it.
• Hostnames are different. Non-ASCII domain names use Punycode (xn--…), not percent-encoding.