URL Encoder

A URL is not free-form text. Certain characters are structural: `?` starts the query string, `&` separates parameters, `=` splits a name from a value, `/` divides path segments, and `#` begins the fragment. If a value you want to transmit contains any of those, it will be read as structure rather than data, and the URL will be parsed into the wrong pieces.

Percent-encoding solves this by replacing a character with `%` followed by its two-digit hexadecimal byte value. A space becomes `%20`, an ampersand becomes `%26`, a question mark becomes `%3F`. The URL parser sees only unreserved characters and percent triplets, so the structure stays unambiguous while the original value survives intact.

The distinction that matters is between reserved characters used structurally and the same characters appearing inside a value. A `&` between parameters must stay literal; a `&` inside a company name must be encoded. Which is which depends on intent, not on the character - which is why encoding has to be applied to each component separately rather than to a whole URL at once.

JavaScript offers two functions and choosing the wrong one is the most common URL bug there is. `encodeURIComponent` encodes everything that is not unreserved, including `/`, `?`, `&`, `=` and `#`. `encodeURI` deliberately leaves those alone because it assumes you are handing it a complete URL whose structure should survive.

The rule is straightforward once stated: use `encodeURIComponent` for individual values - one query parameter, one path segment - and `encodeURI` only for an entire URL you want to make safe without altering its structure. Nearly every practical case is the first one.

Getting it wrong fails in both directions. Using `encodeURI` on a value means an embedded `&` stays literal and splits your parameter in two, which is the shape of a parameter-injection bug. Using `encodeURIComponent` on a whole URL turns every `/` into `%2F` and produces a single unusable string.

Both functions also leave `!`, `'`, `(`, `)` and `*` unencoded, though RFC 3986 lists them as reserved. Most servers cope, but if a strict parser rejects them you have to encode those five manually.

In `application/x-www-form-urlencoded` - the format HTML forms submit and the convention most query strings follow - a space is encoded as `+`, not `%20`. In the URL specification proper, `+` is a literal plus character. Both conventions are in active use, and they collide in query strings.

The practical consequence bites email addresses. Gmail's `user+tag@example.com` sub-addressing is widespread, and if that `+` is not encoded as `%2B`, a form-style decoder reads it as a space and delivers `user tag@example.com`. This is a real and frequent bug in signup flows and unsubscribe links.

The safe approach is to always encode a literal plus as `%2B` and always use `%20` for spaces. `%20` is valid in both conventions, so it removes the ambiguity entirely rather than relying on the decoder guessing correctly.

Percent-encoding operates on bytes, so a non-ASCII character must first be converted to bytes via UTF-8 and then each byte encoded separately. `é` is two bytes in UTF-8 and becomes `%C3%A9`. A CJK character is typically three bytes and becomes three triplets. This is why an encoded non-Latin string looks so much longer than the original.

Double encoding is the failure to watch for. Encode a string twice and `%` itself becomes `%25`, so `%20` becomes `%2520`. Decoding once then yields the literal text `%20` rather than a space. The tell is a `%25` in a URL where you did not expect one, and the cause is almost always two layers of code each helpfully encoding the same value.

The fix is to be deliberate about where encoding happens - typically once, at the point where the URL is assembled - rather than defensively encoding at every layer.