Skip to main content

Developer

URL Encoding Explained: Percent Signs, Plus Signs, and Double Encoding

How percent-encoding works, when to use encodeURIComponent versus encodeURI, why spaces sometimes become plus signs, and how to spot double-encoded URLs.

By 8 min read

Article

A URL can only contain a limited set of characters. Everything else - spaces, accented letters, emoji, and characters that have a structural meaning such as ? and & - has to be written in a form the URL syntax can carry. That form is percent-encoding: a percent sign followed by two hexadecimal digits for each byte.

The idea is simple, but the details produce some of the most common web bugs: search terms that arrive truncated, redirect URLs that break, and links full of %2520. This guide explains the rules and the handful of decisions that prevent those bugs.

Who this is for

Front-end and back-end developers building links or query strings, marketers assembling tracking URLs by hand, and anyone debugging a link that works in one place and breaks in another.

How percent-encoding works

RFC 3986, the URI specification, divides characters into unreserved ones that never need encoding (letters, digits, hyphen, period, underscore, and tilde) and reserved ones that act as delimiters, such as : / ? # [ ] @ ! $ & ' ( ) * + , ; =. Any other character, and any reserved character used as data rather than as a delimiter, is converted to bytes and each byte is written as %XX.

Non-ASCII text is first encoded as UTF-8, so one visible character can become several escapes. The letter é is two bytes in UTF-8 and becomes %C3%A9. A space is a single byte, 0x20, and becomes %20.

  • Space becomes %20
  • & becomes %26, so it no longer separates query parameters
  • = becomes %3D, so it no longer separates a key from its value
  • / becomes %2F when it is part of a value rather than a path separator
  • é becomes %C3%A9 because it is two bytes in UTF-8

Encode the pieces, not the whole URL

The single most useful rule: build a URL from parts, and encode each part as data before you join them. If a user searches for "salt & pepper" and you write ?q=salt & pepper into the URL, the server sees a parameter q with the value "salt " and a second, empty parameter called " pepper". Encoding the value first gives ?q=salt%20%26%20pepper, which arrives intact.

JavaScript provides two built-in functions, and choosing the wrong one is a classic mistake. encodeURIComponent is for a single piece of data, such as one query value or one path segment. It encodes everything except letters, digits, and - _ . ! ~ * ' ( ). encodeURI is for a complete URL that is already structured; it deliberately leaves characters such as / ? & = # alone so the URL keeps working. That means encodeURI will not protect an & inside a value. When in doubt, use encodeURIComponent on each value. ToolMint’s URL Encoder / Decoder uses component encoding for this reason.

Why spaces sometimes become plus signs

HTML forms submitted with the GET method use a slightly different format called application/x-www-form-urlencoded. In that format a space is written as + rather than %20, and a literal plus sign must be written as %2B. The URLSearchParams API in browsers and Node.js follows the form rules, so new URLSearchParams({ q: "a b" }).toString() produces q=a+b.

The trouble starts when the two conventions meet. decodeURIComponent does not turn + into a space, so a value encoded by a form and decoded with decodeURIComponent keeps its plus signs. In the other direction, a phone number like +44 sent without encoding arrives as " 44" because the server reads the plus as a space. Pick one convention per interface and decode with the matching function.

Spotting double encoding

Double encoding happens when a value that is already encoded gets encoded again. The percent sign itself becomes %25, so %20 turns into %2520 and a space now shows up on the page as the literal text %20. It usually means two layers of code each tried to be helpful: a helper that encodes values and a caller that passed in an already-encoded string, or a redirect parameter that was encoded once by the app and again by a framework.

The giveaway is %25 followed by two hex digits. Decoding once and getting text that still contains %XX sequences confirms it. The fix is to find the layer that should own encoding and remove the other one, not to add a second decode step on the receiving side, which will break the next value that legitimately contains a percent sign.

Redirect and callback URLs

OAuth callbacks, login redirects, and tracking links often carry a full URL as the value of a parameter, for example ?next=https://example.com/a?b=1&c=2. Without encoding, the receiving server sees next=https://example.com/a?b=1 and a separate parameter c=2. The entire inner URL must be encoded with encodeURIComponent so its ? & and = become %3F %26 and %3D.

Redirect parameters are also a security boundary. After decoding, check that the destination is a path or host you expect before redirecting, or an attacker can use your domain to bounce visitors to theirs.

Errors you will see

decodeURIComponent throws a URIError when it meets a percent sign that is not followed by two valid hex digits, or a sequence of bytes that is not valid UTF-8. A string like "100% done" cannot be decoded as-is, because "% d" is not a valid escape. If you decode user-supplied text, wrap the call in error handling and decide what a malformed value should become.

URL encoding is not Base64 and not escaping for HTML

Percent-encoding makes text safe inside a URL. It does not hide anything; %70%61%73%73 is just "pass" for anyone who decodes it. Base64 serves a different purpose: it represents binary data as text, and its standard alphabet includes + / and = which themselves need URL encoding, which is why a URL-safe Base64 variant using - and _ exists. Neither one makes text safe to insert into HTML; that needs HTML entity escaping.

A quick checklist

Before you ship code that builds URLs:

  • Encode each query value and path segment with encodeURIComponent, then join them.
  • Never run encodeURI on a value; it leaves & = and ? unencoded.
  • Use URLSearchParams when you want form-style encoding, and decode with it too.
  • Look for %25 in logs as a sign of double encoding.
  • Encode full URLs passed as parameters, and validate them after decoding.
  • Handle URIError when decoding anything a user typed.

Takeaway

Percent-encoding is a byte-level escape for characters that would otherwise change the meaning of a URL. Encode data, not structure; use component encoding for values; keep form-style plus signs and %20 apart; and when you see %2520, look for the second layer that is encoding something already encoded.