encodeURI vs encodeURIComponent

The two-line answer

• encodeURI — encodes a whole URL. Leaves URL syntax characters (: / ? # [ ] @ ! $ & ' ( ) * + , ; =) alone, because the URL needs them.
• encodeURIComponent — encodes a single piece of a URL. Escapes URL syntax characters, because you're putting this inside a URL component (path segment or query parameter value).

If you don't already know your input contains a complete URL, you want encodeURIComponent.

The character difference

The two functions agree on letters, digits, and the unreserved characters - _ . ~. They split on the URL syntax characters:

The + row is highlighted because it's a footgun on its own — see below.

The classic bug

You build a URL by string concatenation:

const q = "shoes & socks";
const url = "https://example.com/search?q=" + encodeURI(q);
// → https://example.com/search?q=shoes%20&%20socks

The & didn't get escaped. The receiving server sees the URL as having two query parameters: q=shoes and %20 (with no value). Your search breaks.

Fix:

const url = "https://example.com/search?q=" + encodeURIComponent(q);
// → https://example.com/search?q=shoes%20%26%20socks

Or, the canonical way:

const u = new URL("https://example.com/search");
u.searchParams.set("q", q);
url.toString();
// → https://example.com/search?q=shoes+%26+socks

Note that URLSearchParams encodes spaces as + (form-style), while encodeURIComponent uses %20. Both are valid; servers accept either when parsing queries.

The + / space gotcha

URLs have two standards for spaces:

• Generic URL syntax (RFC 3986) uses %20. This is what encodeURIComponent emits.
• Form-encoded data (the historical application/x-www-form-urlencoded) uses + for a space, and %2B for a literal +.

The bug surfaces when a value containing a literal + is sent through encodeURIComponent (which doesn't escape +) and read by a server that treats + as a space:

const v = "1+1=2";
encodeURIComponent(v);                    // "1%2B1%3D2" — wait, no
                                           // actually it's "1%2B1%3D2"

OK, that one's fine — encodeURIComponent escapes =. But test on the destination server. Many frameworks (PHP's $_GET, Express's query parser) decode + as a space. If you stick a literal + into a URL via direct string concat, watch out.

The five percent-decoders, ordered

For completeness, JavaScript has these:

• encodeURI / decodeURI — for full URLs.
• encodeURIComponent / decodeURIComponent — for URL pieces. Default to these.
• escape / unescape — deprecated. Don't use. They're not UTF-8 aware. Removed in modern strict interpretations.
• URLSearchParams — for building query strings. Most robust option for that case.
• new URL(base) — for assembling URLs. Combine with URLSearchParams via url.searchParams.

Decision flowchart

1. Are you building a URL? → Use new URL(base) and its searchParams. Don't concatenate strings.
2. Are you encoding one piece of an existing URL (a path segment, a single query value)? → encodeURIComponent.
3. Are you encoding a complete URL whose pieces are already correct but contains some non-ASCII characters? → encodeURI. (Rare. Usually means a malformed URL was built upstream.)
4. Are you using escape? → Stop. It's deprecated.

Reference

• RFC 3986 — Uniform Resource Identifier: Generic Syntax. The spec the functions implement.
• MDN: URLSearchParams — modern API for query strings.

FAQ

Open the URL encoder →