Why URLs need encoding
A URL may only contain a limited set of ASCII characters. Anything else — spaces, most punctuation, accents, emoji — has to be written as % followed by its byte value in hex. That is "percent-encoding". These are the ones you'll see most:
| Character | Encoded | Character | Encoded |
|---|---|---|---|
| space | %20 | & | %26 |
? | %3F | = | %3D |
/ | %2F | # | %23 |
+ | %2B | @ | %40 |
Gotcha — component vs whole URL. Component encoding (the default) escapes /, ? and & — correct for a value you're dropping into a query string. Whole-URL encoding leaves those structural characters alone so a complete link still works. Encode a value with the wrong one and your query string breaks.
Which characters are safe
Letters, digits and the four marks - _ . ~ are unreserved and never need escaping. Characters such as / ? # & = : are reserved because they carry structural meaning in a URL. The deciding question is always whether a character is data or structure: an & that separates two query parameters must stay literal, but an & inside a value has to become %26 or it will be misread as a separator.
The two JavaScript functions people confuse
JavaScript offers two encoders, and picking the wrong one is a common bug.
| Function | Escapes / ? & = ? | Use for |
|---|---|---|
encodeURIComponent | Yes | A single value — one query parameter or path segment |
encodeURI | No (keeps structure) | A whole URL you do not want to break apart |
const url = "https://api.example.com/search?q="
+ encodeURIComponent("c++ & rust");
// → ...?q=c%2B%2B%20%26%20rustThe rule: encode each piece with the component function, then join the pieces with literal /, ?, & and = yourself.
The same character, encoded differently in different places
"URL encoding" isn't one rule, it's several that depend on where in the URL you are. A space in the path is %20. A space in HTML form data sent as application/x-www-form-urlencoded is a +, a quirk left over from early web forms — which is why a value round-tripped through the wrong decoder comes back with + signs where spaces should be. The query string, the path, and the fragment after # each allow slightly different characters unescaped, so a character that's safe in one position still needs encoding in another. This is the real reason the "encode a value, not the whole URL" advice keeps coming up: only you know which part of the URL a given string is going into.
When decoding becomes a vulnerability
Encoding is also a security surface, because some systems decode more than once. If a server decodes a path, hands it to another layer that decodes again, an attacker can hide ../ as %252e%252e%252f — that's a double-encoded ../ — and slip past a filter that only checked the once-decoded form, reaching files it shouldn't. The same trick has been used to sneak past web application firewalls. The takeaway for everyday code: decode exactly once, validate the decoded result, and never assume an encoded string is automatically safe just because the dangerous characters are hidden behind percent signs.
Does the part after # get sent to the server?
No. The fragment (everything after the #) stays in the browser and isn't sent in the HTTP request, which is why single-page apps use it for client-side routing. Only the path and query reach the server, so that's what your encoding needs to satisfy.
What is Punycode, and how do international domains get encoded?
Domain names can't hold non-ASCII characters directly, so an internationalized domain like münchen.de is converted to an ASCII form (xn--mnchen-3ya.de) called Punycode. It's a separate scheme from percent-encoding — percent-encoding is for the path and query, Punycode is for the host portion of the URL.
Why does my decoded value have + instead of spaces?
Because it was encoded as HTML form data (application/x-www-form-urlencoded), where a space is +, but decoded as a normal URL where a space is %20. Match the decoder to how the value was encoded.
Why did one character become several % codes?
Non-ASCII characters are first encoded as UTF-8, which can take several bytes, and each byte is then percent-escaped. A single emoji can therefore become four percent-codes.
My value shows up as %2520 — what happened?
Double-encoding: a string that was already percent-encoded got encoded again, so its % turned into %25. Decode it once, then encode the original value a single time.
Is a space %20 or +?
In the path it's always %20. The + only means space in the query string under application/x-www-form-urlencoded form data. When in doubt, %20 is safe everywhere.
Which mode should I use for a search term?
Component (default). A search term is a value, so / and & inside it must be escaped or they'll be read as URL structure.
Why does decoding fail sometimes?
A lone % not followed by two hex digits is invalid percent-encoding. Fix the stray % (write it as %25) and try again.