A URL is not a string of text; it is a grammar with reserved characters. A ? starts a query, & separates parameters, # starts a fragment, and / separates path segments. If a value contains one of those characters, it must be percent-encoded or the URL will be parsed differently than intended.
The reserved set
| Character | Encoded | Meaning in a URL |
|---|---|---|
| space | %20 |
Illegal in a URL |
& |
%26 |
Query parameter separator |
= |
%3D |
Key/value separator |
? |
%3F |
Query start |
# |
%23 |
Fragment start |
/ |
%2F |
Path separator (or a literal slash in a value) |
% |
%25 |
Percent itself |
+ |
%2B |
Plus sign, not a space in a path |
A literal percent sign is the subtle one. % starts an escape sequence, so a raw % followed by non-hex characters makes the URL invalid. Encode it as %25.
Component versus full URL
JavaScript has two built-in encoders with different jobs:
encodeURIComponent("a b&c") // "a%20b%26c"
encodeURI("https://x.com/a b?q=1") // "https://x.com/a%20b?q=1"
encodeURIComponentescapes every character with syntactic meaning, including:,/,?,&,=and#. Use it for a query value, a path segment, a filename or a redirect target.encodeURIleaves the structural characters alone and only escapes characters that are illegal everywhere, such as spaces. Use it to clean up a complete URL.
Encoding a full URL with encodeURIComponent turns it into an opaque value:
https%3A%2F%2Fexample.com%2Fa%3Fb%3Dc
That is a valid query parameter, but it is no longer a URL. If you then pass it to a browser, it will not navigate.
Plus signs and form encoding
HTML forms with application/x-www-form-urlencoded encode spaces as +. That is a form convention, not a URI rule. encodeURIComponent produces %20. When decoding a query string, treat + as a space only if you know the source used form encoding. Otherwise a literal plus in a value is silently lost.
Double encoding
The most common production bug is encoding twice:
original: a b
encoded: a%20b
encoded again: a%2520b
%25 is the escape for a literal percent, so the receiver decodes %2520 back to %20, not to a space. Signed URLs, redirect chains and OAuth callbacks often break this way. The signature is computed over one canonical form, and the transmitted URL is another.
Rule: decode once, inspect the result, encode once for the target context. Do not “clean up” a URL that is already encoded.
Path versus query
The rules differ by component:
- In a path segment,
/must be encoded as%2Fif it is part of the value, not a separator. - In a query value,
/may remain unencoded in many parsers, but encoding it is safer. - In a fragment, the rules are loosest; encode anything that could be mistaken for a separator.
- In user info before the
@, encode@,:and/.
Do not build a URL by concatenating strings without encoding each value. Use a URL builder or encode each component before joining.
Unicode
Browsers display internationalized URLs, but the wire format is percent-encoded UTF-8. A Chinese path segment becomes a sequence of %E4%B8%AD... bytes. Encoding the characters as UTF-8 first is mandatory; different encodings produce different byte sequences and therefore different URLs.
A practical checklist
- Identify the component: path segment, query key, query value, fragment.
- Encode with the rule for that component, not a generic string replace.
- Encode
%itself if it appears in the value. - Do not encode twice.
- Decode and inspect when debugging; compare the canonical form with the signature.
- Keep spaces as
%20unless the receiver explicitly expects form encoding.
The URL encoder supports both component and full-URL modes and reports invalid percent sequences. If you are debugging a signed URL, compare the decoded value before and after the signature step; that is usually where the extra encode hides.