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"
  • encodeURIComponent escapes every character with syntactic meaning, including :, /, ?, &, = and #. Use it for a query value, a path segment, a filename or a redirect target.
  • encodeURI leaves 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 %2F if 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

  1. Identify the component: path segment, query key, query value, fragment.
  2. Encode with the rule for that component, not a generic string replace.
  3. Encode % itself if it appears in the value.
  4. Do not encode twice.
  5. Decode and inspect when debugging; compare the canonical form with the signature.
  6. Keep spaces as %20 unless 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.