encodeURI vs encodeURIComponent: Key Differences, Character Sets, and Pitfalls

The Core Distinction: Protocol vs Parameter

JavaScript provides two built-in global functions for percent-encoding strings: encodeURI() and encodeURIComponent(). While both convert non-ASCII characters into UTF-8 percent-encoded bytes (%HH), they differ critically in how they handle URI reserved delimiter characters (:, /, ?, #, &, =, +, @).

• `encodeURI()`: Designed to encode a complete, full URI. It preserves structural URI syntax characters (e.g. http://, slashes, query delimiters ? and &) while encoding unsafe characters like spaces (%20) and Unicode symbols.
• `encodeURIComponent()`: Designed to encode a single query parameter key or value. It escapes structural URI delimiters (&, =, /, ?, #, +) so that user inputs containing special characters do not break the URL structure.

Character Set Comparison Table

The following matrix illustrates which characters are preserved versus escaped by each function:

Practical Code Examples

Consider constructing an API request URL where the search query is "Salt & Pepper = $5.00":

const query = 'Salt & Pepper = $5.00';
const base = 'https://api.cosharex.com/search';

// WRONG: Using encodeURI on parameters leaves '&', '=', and '$' intact!
const wrongUrl = `${base}?q=${encodeURI(query)}`;
console.log(wrongUrl);
// Output: https://api.cosharex.com/search?q=Salt%20&%20Pepper%20=%20$5.00
// Bug: The server sees two parameters: 'q'='Salt ' and ' Pepper '=' $5.00'

// CORRECT: Using encodeURIComponent on individual query parameters
const correctUrl = `${base}?q=${encodeURIComponent(query)}`;
console.log(correctUrl);
// Output: https://api.cosharex.com/search?q=Salt%20%26%20Pepper%20%3D%20%245.00
// Success: The server correctly decodes 'q' as 'Salt & Pepper = $5.00'

The Modern Approach: URL & URLSearchParams

In modern JavaScript (Node.js 18+ and all evergreen browsers), manual string interpolation with encodeURIComponent is largely superseded by the standard URL and URLSearchParams classes, which handle percent-encoding automatically according to WHATWG URL standards:

// Robust, standard-compliant URL construction
const url = new URL('https://api.cosharex.com/v1/search');

// Automatically encodes keys and values properly
url.searchParams.set('q', 'Salt & Pepper = $5.00');
url.searchParams.set('category', 'p2p/files');
url.searchParams.set('page', '1');

console.log(url.toString());
// https://api.cosharex.com/v1/search?q=Salt+%26+Pepper+%3D+%245.00&category=p2p%2Ffiles&page=1

Common Developer Pitfalls & Bugs

• Double Encoding Bug: Running encodeURIComponent() on a string that was already percent-encoded turns %20 into %2520. Always encode raw data at the boundary before transmission.
• Unescaped Single Quotes: Note that neither encodeURI nor encodeURIComponent escapes single quotes (') or parentheses (()). When injecting values into SQL or HTML attributes, additional escaping is mandatory.
• Malformed URI Errors: Calling decodeURIComponent() on an invalid percent sequence (like "%E0%A4") throws a URIError. Always wrap decoders in try...catch blocks when handling untrusted user input.