What is the Difference Between encodeURI and encodeURIComponent?

What is encodeURI()?

encodeURI() is a built-in JavaScript function designed to encode a complete Uniform Resource Identifier (URI). It converts characters that are not valid in a URI into their percent-encoded equivalents, but it intentionally preserves characters that have structural meaning within a URI.

Specifically, encodeURI() does not encode the following characters: A-Z a-z 0-9 ; , / ? : @ & = + $ - _ . ! ~ * ' ( ) #. This means the overall structure of the URL remains intact after encoding.

// encodeURI() preserves URL structure
const url = 'https://example.com/my page?name=John Doe&city=New York';
console.log(encodeURI(url));
// "https://example.com/my%20page?name=John%20Doe&city=New%20York"
// Notice: :, /, ?, &, and = are NOT encoded

This behavior makes encodeURI() ideal when you have a complete URL that may contain spaces or non-ASCII characters but whose structural characters (protocol separator, path delimiters, query string markers) should remain as-is.

What is encodeURIComponent()?

encodeURIComponent() is designed to encode a single component of a URI, such as a query parameter value or a path segment. Unlike encodeURI(), it encodes almost every special character, including those that have structural meaning in URLs.

The only characters encodeURIComponent() does not encode are:A-Z a-z 0-9 - _ . ! ~ * ' ( ). Everything else, including /, ?, &, =, #, and :, gets percent-encoded.

// encodeURIComponent() encodes everything except unreserved chars
const value = 'Tom & Jerry / Friends?';
console.log(encodeURIComponent(value));
// "Tom%20%26%20Jerry%20%2F%20Friends%3F"
// Notice: &, /, and ? ARE encoded

// Building a URL with a query parameter
const url = 'https://example.com/search?q=' + encodeURIComponent(value);
// "https://example.com/search?q=Tom%20%26%20Jerry%20%2F%20Friends%3F"

Because it encodes structural characters, you should never use encodeURIComponent()on a complete URL. Doing so would encode the ://, all / path separators, and the ? query delimiter, rendering the URL unusable.

Key Differences at a Glance

When to Use Each Function

The rule is straightforward: use encodeURI() when you want to encode a complete URL while keeping its structure valid. Use encodeURIComponent() when you want to encode a single value that will be inserted into a URL.

// Scenario 1: Encoding a complete URL with spaces
const fullUrl = 'https://example.com/my documents/file name.pdf';
const encoded = encodeURI(fullUrl);
// "https://example.com/my%20documents/file%20name.pdf"

// Scenario 2: Building a URL from parts
const baseUrl = 'https://api.example.com/search';
const query = 'price >= 100 & category = books';
const finalUrl = baseUrl + '?q=' + encodeURIComponent(query);
// "https://api.example.com/search?q=price%20%3E%3D%20100%20%26%20category%20%3D%20books"

// Scenario 3: Encoding a redirect URL as a parameter
const redirectUrl = 'https://example.com/callback?token=abc';
const loginUrl = 'https://auth.example.com/login?redirect=' +
  encodeURIComponent(redirectUrl);
// The entire redirect URL is encoded as a single parameter value

Common Mistakes and How to Avoid Them

Mistake 1: Using encodeURI() for query parameter values. BecauseencodeURI() does not encode & or =, using it on a parameter value that contains these characters will corrupt the query string structure.

// WRONG
const bad = 'https://example.com/search?q=' + encodeURI('salt & pepper');
// "https://example.com/search?q=salt%20&%20pepper"
// The server sees q="salt " and an extra parameter " pepper"

// CORRECT
const good = 'https://example.com/search?q=' + encodeURIComponent('salt & pepper');
// "https://example.com/search?q=salt%20%26%20pepper"

Mistake 2: Using encodeURIComponent() on a full URL. This destroys the URL structure by encoding all slashes, colons, and question marks.

// WRONG
console.log(encodeURIComponent('https://example.com/path?key=value'));
// "https%3A%2F%2Fexample.com%2Fpath%3Fkey%3Dvalue"
// This is no longer a valid URL!

// CORRECT
console.log(encodeURI('https://example.com/path?key=value'));
// "https://example.com/path?key=value" (already valid, nothing to encode)

Mistake 3: Double encoding. If a string is already percent-encoded, encoding it again will encode the % signs, turning %20 into%2520. Always check whether a value has already been encoded before applying encoding functions.

A safer modern alternative is the URL and URLSearchParams APIs, which handle encoding automatically and help you avoid these pitfalls entirely.