URL encoding and decoding: whole strings, parameter values, and %20

When you need it

A URL contains non-ASCII text, spaces, or characters such as & that double as separators. Pasted in raw, the link gets truncated or parsed incorrectly, so the value must be encoded first. If a value already contains %26, Encode values decodes it before re-encoding, so it does not become %2526.

You pull a string like %E4%B8%AD%E6%96%87 out of a log, an analytics event, or an email and need it readable. Four-byte UTF-8 sequences such as emoji decode correctly too.

A third-party callback requires a return_url that must itself be encoded inside another parameter. Encoding the whole string and encoding only the values give different results, and picking the wrong one adds or drops a layer.

• A non-ASCII or space-containing parameter value
• Decode %E4%B8%AD%E6%96%87 from a log or email
• Nest a callback URL inside another parameter
• Normalise a string before signing it

How to get it right

Know the two functions. encodeURIComponent escapes separators such as / ? & = and is meant for a single parameter value; encodeURI leaves them alone and is meant for a whole URL. The whole-string mode here uses the former, so :// becomes %3A%2F%2F — avoid it when the URL structure must survive.

Encode values only splits on ? and &, processes each value, and decodes existing percent-encoding before re-encoding it, which prevents %2526 from stacking up. It does not handle the # fragment or ; separators, so split those yourself when they matter.

A space is %20, not +. encodeURIComponent follows RFC 3986 and always writes a space as %20; writing + for a space is the HTML form rule from application/x-www-form-urlencoded. Most frameworks accept both in a query string, but signing algorithms, OAuth, and some older gateways treat + as a literal plus. When you need +, generate it with URLSearchParams instead of replacing characters by hand, which would also corrupt a correct %2B.

An invalid percent-escape error usually means an isolated %, a %ZZ, or a truncated sequence such as %E4. Common causes: the link was encoded twice, a chat app truncated it, or the original text literally contained 100%. A literal percent sign must be written %25. The tool fails as a whole on an invalid sequence rather than returning a half-decoded string.

If one decode still looks like garbage, the text was probably encoded twice, which is common when a callback URL is nested inside another redirect parameter. Each decode removes one layer: %25E4%25B8%25AD becomes %E4%B8%AD and then 中. Clicking again is fine as long as you know which layer you are on; the real fix is to encode once at the source.

• encodeURIComponent for one value, encodeURI for a whole URL
• Encode values only avoids stacking %2526
• A space is %20; + is the form rule
• An invalid % fails the whole decode; check every percent sign

Alternatives and limits

In code, use URL and URLSearchParams. They handle encoding, +, and ordering according to the spec, and new URL(...).searchParams.set(...) encodes values for you.

Use encodeURI when a whole URL must keep its structure. To build a form body or a string that will be signed, use URLSearchParams.toString(), which applies the form rule and emits +.

The limits here: only ? and & are used as separators, so # fragments and ; are not handled; spaces are %20 rather than +; an invalid percent sequence fails outright with no best-effort decode; and there is no URL normalisation of case, default ports, or .. path segments.

• Use URL and URLSearchParams in code
• Whole URL → encodeURI
• Form body or signing → URLSearchParams
• Normalisation → a dedicated library