Developer

encodeURI vs encodeURIComponent Explained

Dev Nexus4 min read

The clear difference between encodeURI and encodeURIComponent, with examples showing which one to use for a value versus a whole URL.

JavaScript ships two built-in URL encoders — encodeURI and encodeURIComponent — and picking the wrong one is a classic source of broken query strings. They look interchangeable but escape different sets of characters on purpose.

This post explains the difference in one sentence, backs it up with examples, and gives you a rule you can apply without thinking each time.

The Problem

The trouble is that both functions accept any string and return something that looks encoded, so a mistake does not throw an error — it silently produces a subtly wrong URL. Use encodeURI on a query value and its & and = stay raw, so the value merges into the surrounding query and parameters go missing. Use encodeURIComponent on a whole URL and the :// and / get escaped, turning a valid address into an unusable blob.

Because the failure is silent, it often surfaces far downstream — a redirect that loses part of its target, an API call that drops a filter, a search that returns the wrong results. You are left debugging the server when the bug was the choice of encoder.

The Solution

The rule fits in one line: use encodeURIComponent for a single value you are inserting into a URL, and encodeURI for a whole URL you want to make safe without altering its structure.

The difference is which characters they leave alone. encodeURI preserves the reserved characters that give a URL its shape — : / ? # [ ] @ ! $ & ' ( ) * + , ; = — because it assumes you handed it a complete, valid URL. encodeURIComponent escapes those reserved characters too, because inside a single value they are data, not syntax.

A quick example. Given the value a&b=c:

encodeURIComponent("a&b=c") returns a%26b%3Dc — safe to drop after ?q=.
encodeURI("a&b=c") returns a&b=c — unchanged, and now it corrupts your query.

In practice you build a URL by encoding each value with encodeURIComponent and concatenating, rather than encoding the finished string. The URL Encoder mirrors both behaviours with its component and full-URL scopes, so you can preview exactly what each produces before committing it to code. It runs in your browser, so nothing is uploaded.

Step-by-Step Guide

1
Decide: value or whole URL?
Ask whether you are encoding one piece of data going into a URL, or a complete URL that already has its structure. A value means encodeURIComponent; a full URL means encodeURI.
2
Use encodeURIComponent for each parameter
Encode every query value on its own: ` ?q=${encodeURIComponent(term)}undefined& = ? #` inside the value so it cannot break out into the query syntax.
3
Use encodeURI only for a finished URL
Reach for encodeURI when you have an assembled URL that may contain a space or non-ASCII character and you just need it to be valid — it leaves :/?# intact.
4
Never encodeURI a raw value
If the string is a single value, encodeURI will not escape its reserved characters, so a&b stays a&b. That silently merges into the surrounding query. Use encodeURIComponent instead.
5
Preview both before you ship
Paste your value into the tool and compare component versus full-URL scope. Seeing a%26b%3Dc next to a&b=c makes the right choice obvious.

Common Mistakes

Using encodeURI for query values
This is the most common error. encodeURI leaves &, =, and + untouched, so a value containing them corrupts the query string and drops parameters. Query values need encodeURIComponent.
Using encodeURIComponent on a full URL
It escapes the : and / in https://, producing https%3A%2F%2F... — no longer a working URL. Only encode complete URLs with encodeURI, or better, encode the parts.
Encoding an already-assembled URL
Encoding the finished string rather than each value is guesswork. Build the URL by encoding each component with encodeURIComponent and joining them, so every piece is escaped correctly.
Forgetting that neither escapes everything
Both functions leave ! ' ( ) * unescaped, and encodeURIComponent does not escape them either. For strict contexts (like OAuth signatures) you may need to escape those manually after calling the function.

Frequently Asked Questions

What is the one-line difference between encodeURI and encodeURIComponent?

`encodeURI` encodes a whole URL and preserves reserved characters like `: / ? #`, while `encodeURIComponent` encodes a single value and escapes those reserved characters too.

Which one should I use for a query parameter?

Use `encodeURIComponent`. It escapes `&`, `=`, `?`, and `#`, which is essential when those characters appear inside a value so they do not break the query string.

Why does encodeURIComponent break my full URL?

Because it escapes the `:` and `/` that structure the URL, turning `https://` into `https%3A%2F%2F`. For a complete URL use `encodeURI`, or encode each part individually.

Do these functions handle non-ASCII characters?

Yes. Both encode non-ASCII characters as UTF-8 byte sequences, so `é` becomes `%C3%A9`. The difference between them is only in how they treat reserved ASCII characters.

Are there characters neither function escapes?

Yes. Both leave `! ' ( ) *` unescaped, and the unreserved set `A-Z a-z 0-9 - _ . ~`. If a strict context requires those escaped, do it manually after calling the function.