encodeURIComponent vs encodeURI: When to Use Which

JavaScript ships with two URL-encoding functions with almost identical names, and the difference between them is exactly the kind of detail that's easy to skip past — until one of them silently breaks a URL, or the other leaves a query value unsafe to insert into one.

What each one actually escapes

encodeURIComponent() is the aggressive one — it escapes every character that has structural meaning anywhere in a URL: : / ? # & =, plus spaces and non-ASCII characters. It assumes the string you're giving it is a single piece of a URL — a query parameter's value, a path segment — not a complete URL with its own structure to preserve.

encodeURI() is more conservative — it leaves those structural characters alone (: / ? # & = pass through untouched) and only escapes things that are never valid raw in a URL under any circumstances, like spaces and non-ASCII characters. It assumes you're handing it a complete, already-structured URL that should stay recognizable as a URL after encoding.

The mistake that breaks things

Run a full URL like https://example.com/search?q=hello through encodeURIComponent(), and its own :// and ? get percent-escaped along with everything else — the result is no longer a usable URL at all, just an encoded blob. This is the most common version of the mistake: reaching for the "safer-sounding" component function on something that was never meant to be treated as a single opaque value.

The mistake that leaves things unsafe

The opposite error is subtler: encoding a single query value with encodeURI() instead of encodeURIComponent(). Say the value itself legitimately contains an & or = — a search term like "salt & pepper", for instance. encodeURI() won't touch that &, since it treats it as a structurally valid URL character. Once that value is inserted into a real query string, the unescaped & gets misread as the start of a second parameter, silently corrupting the query rather than raising any error.

A simple rule of thumb

If what you're encoding is a complete URL and you want it to stay recognizably a URL, use encodeURI(). If what you're encoding is going to be inserted into a URL — a query parameter value, a value being appended to a path, a redirect target embedded as a parameter in another URL — use encodeURIComponent(). In practice, the component version is what most day-to-day work actually needs, since building a query string parameter-by-parameter is a far more common task than encoding an already-complete URL.

A related, older convention: the "+" for space

Standard percent-encoding represents a space as %20. A separate, older convention used specifically in application/x-www-form-urlencoded form submissions represents a space as + instead. These aren't interchangeable — a literal + decoded under the form convention becomes a space, but decoded under standard percent-encoding rules, a literal + just stays a plus sign. Mixing the two conventions up is a common source of stray plus signs or missing spaces showing up after decoding.

Try it

FreeToolDev's bulk URL encoder/decoder supports both modes explicitly labeled — "Component" for query values, "Full URL" for complete URLs — so the choice is made deliberately rather than guessed, and processes a whole list at once.