URL Encoder / Decoder

What percent-encoding is for

A URL may only contain a limited set of characters, and some of those have jobs to do: / separates path segments, ? starts the query, & separates parameters, = joins a name to its value and # starts the fragment. To put any other character into a URL — or one of those characters without its special meaning — it is written as a percent sign followed by two hexadecimal digits giving its byte value. A space becomes %20, an ampersand %26.

RFC 3986, the URI standard, divides characters into unreserved ones that never need encoding — the letters A to Z and a to z, the digits, and the hyphen, full stop, underscore and tilde — and reserved ones with special meanings: : / ? # [ ] @ and ! $ & ' ( ) * + , ; =. Everything else must be encoded. The standard recommends uppercase hex digits, %2F rather than %2f, though both are valid and decode identically.

encodeURI or encodeURIComponent

Browsers offer two encoders, and choosing the wrong one is behind a great many broken links. encodeURI is for a complete URL: it leaves the structural characters alone so the address still works, and encodes only what cannot appear in a URL at all, such as spaces and non-ASCII letters. Applied to https://example.com/a file.pdf?x=1&y=2, it gives https://example.com/a%20file.pdf?x=1&y=2.

encodeURIComponent is for one piece that will be inserted into a URL — a single query value or a path segment. It encodes the structural characters as well, because inside a value they must not be read as structure. A search term of “salt & pepper” becomes salt%20%26%20pepper; left unencoded, the & would end the parameter and start a new one called pepper. This page opens on component encoding because that is the job people most often need done.

Encoding a whole URL with encodeURIComponent is the opposite mistake: https://example.com becomes https%3A%2F%2Fexample.com, which is right only when the entire URL is itself a parameter value, such as a redirect target. One small gap: encodeURIComponent leaves ! ' ( ) and * unencoded even though RFC 3986 reserves them. That rarely matters, but schemes that sign URLs, such as OAuth 1.0, need them encoded too.

Plus signs and %20

There are two conventions for spaces. RFC 3986 encodes a space as %20 everywhere. HTML forms, and the application/x-www-form-urlencoded format they submit, write a space in the query string as + instead, which is why search URLs often look like ?q=red+shoes. JavaScript's URLSearchParams follows the form convention.

This tool follows RFC 3986. Encoding produces %20, which servers decode correctly as a space under either convention. Decoding does not turn + into a space, because in a path, or in any URL that is not form-encoded, a plus is a literal plus. If you are decoding a form-encoded query string — the kind with + between words — replace each + with a space first, or the pluses will stay.

The reverse trap catches people constantly: a literal + inside a form-encoded value must be sent as %2B, or the server will read it as a space. Phone numbers with a leading + and email addresses that use plus-addressing are the usual victims.

Non-English text, emoji and decoding errors

Percent-encoding works on bytes, not characters, so non-ASCII text is first converted to UTF-8 and each byte is encoded. é is two bytes and becomes %C3%A9; the rupee sign ₹ is three, %E2%82%B9; an emoji such as 😀 is four, %F0%9F%98%80. Older systems that used other character sets produced different bytes for the same letter, which is why a URL from one can decode to gibberish in another. UTF-8 is what browsers and the URL standard use today.

Decoding fails when the input is not a valid sequence: a lone % with no digits after it, a % followed by something that is not hexadecimal, or a multi-byte UTF-8 sequence that has been cut short, such as %E2%82 without its final byte. The tool reports the error rather than guessing.

Domain names are handled differently. An international domain such as münchen.de is converted to an ASCII form called Punycode — xn--mnchen-3ya.de — not percent-encoded.

Double encoding, the most common URL bug

Encoding something that is already encoded turns the % of %20 into %25, giving %2520, and a link that should open “my file.pdf” asks for “my%20file.pdf” instead. If you see %25 followed by two hex digits in a URL, something encoded it twice: decode once and look again. In code, the cure is to encode each value exactly once, at the moment it is placed into the URL, and never to encode a URL that has already been assembled.

And decoding is not sanitising. A decoded value is exactly as untrusted as it was before, so never insert a decoded URL parameter into a web page without escaping it for HTML first.