encodeURIComponent vs encodeURI: When to Use Which

The Two JavaScript URL Encoding Functions

JavaScript provides two built-in functions for URL encoding: encodeURI() andencodeURIComponent(). While they may seem similar, using the wrong one can lead to broken URLs, security vulnerabilities, or data corruption. Understanding the difference is critical for web developers.

encodeURI() - For Complete URIs

encodeURI() is designed to encode a complete URI. It encodes all characters except those that have special meaning in a URI structure. Specifically, it does NOT encode:

• Reserved characters: ; , / ? : @ & = + $ #
• Unreserved characters: letters, digits, - _ . ! ~ * ' ( )

// encodeURI preserves URI structure
encodeURI('https://example.com/path?q=hello world&lang=en')
// "https://example.com/path?q=hello%20world&lang=en"
// Note: :, /, ?, =, & are NOT encoded

encodeURIComponent() - For URI Components

encodeURIComponent() is designed to encode a single component of a URI (such as a query parameter value). It encodes ALL characters except:

• Unreserved characters: letters, digits, - _ . ! ~ * ' ( )

// encodeURIComponent encodes everything except unreserved chars
encodeURIComponent('hello world & goodbye')
// "hello%20world%20%26%20goodbye"
// Note: & IS encoded because it's a reserved character

// Using it for a query parameter value
const url = 'https://example.com/search?q=' +
  encodeURIComponent('cats & dogs');
// "https://example.com/search?q=cats%20%26%20dogs"

Common Mistakes

Mistake 1: Using encodeURI for Query Values

If you use encodeURI() to encode a query parameter value that contains an ampersand, the ampersand will not be encoded and will be interpreted as a parameter separator, breaking your URL.

// WRONG: ampersand in value breaks the URL
const badUrl = 'https://api.example.com/search?q=' +
  encodeURI('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20&%20Jerry"
// Server sees: q="Tom " and a parameter " Jerry" with no value

// CORRECT: use encodeURIComponent
const goodUrl = 'https://api.example.com/search?q=' +
  encodeURIComponent('Tom & Jerry');
// "https://api.example.com/search?q=Tom%20%26%20Jerry"
// Server correctly sees: q="Tom & Jerry"

Mistake 2: Using encodeURIComponent for Full URLs

If you use encodeURIComponent() on an entire URL, it will encode the colons, slashes, question marks, and other structural characters, making the URL completely unusable.

When to Use Which: The Simple Rule

• Use encodeURI() when you have a complete URI that might contain spaces or non-ASCII characters but the structure is valid
• Use encodeURIComponent() when you are encoding a single piece of data that will be placed into a URI (query parameter values, path segments, etc.)

The URLSearchParams Alternative

Modern JavaScript provides the URLSearchParams API which handles encoding automatically. This is often the best approach for building query strings:

const params = new URLSearchParams({
  q: 'Tom & Jerry',
  category: 'cartoons & animation',
  page: '1'
});

const url = 'https://example.com/search?' + params.toString();
// "https://example.com/search?q=Tom+%26+Jerry&category=cartoons+%26+animation&page=1"

// Or use the URL API
const url2 = new URL('https://example.com/search');
url2.searchParams.set('q', 'Tom & Jerry');
console.log(url2.toString());