URL Encoding in JavaScript: encodeURIComponent vs encodeURI

JavaScript provides two built-in functions for URL encoding: encodeURIComponent() and encodeURI(). They look similar but behave very differently, and picking the wrong one is a common source of broken API calls and malformed links.

The short answer: use encodeURIComponent() when encoding a value that goes inside a URL (like a query parameter or path segment). Use encodeURI() only when encoding a full URL that's already structured correctly.

encodeURIComponent: Encode a Single Value

encodeURIComponent() encodes every character except: A–Z a–z 0–9 - _ . ! ~ * ' ( )

That means it does encode slashes, question marks, ampersands, equals signs, and colons — all the characters that carry structural meaning in a URL.

encodeURIComponent('hello world & more')
// Returns: 'hello%20world%20%26%20more'

encodeURIComponent('price=100¤cy=USD')
// Returns: 'price%3D100%26currency%3DUSD'

Use this when you're building a query string and want to safely include user input as a value:

const query = encodeURIComponent(userInput);
const url = 'https://api.example.com/search?q=' + query;

encodeURI: Encode a Full URL

encodeURI() leaves URL-structural characters alone: : / ? # [ ] @ ! $ & ' ( ) * + , ; =

It only encodes characters that are never valid anywhere in a URL, like spaces, non-ASCII characters, and control characters.

encodeURI('https://example.com/search?q=hello world')
// Returns: 'https://example.com/search?q=hello%20world'

// Note: the & and = are NOT encoded
encodeURI('https://example.com/?a=1&b=2')
// Returns: 'https://example.com/?a=1&b=2' (unchanged)

The problem: if your query values contain ampersands or equals signs, encodeURI() won't encode them, breaking your request. For most real-world API work, encodeURIComponent() on individual values is the right choice.

Sell Custom Apparel — We Handle Printing & Free Shipping

How to Build Query Strings Without Breaking Them

The cleanest way to build query strings in modern JavaScript is URLSearchParams. It handles encoding automatically:

const params = new URLSearchParams({
  q: 'coffee shops & cafes',
  city: 'New York',
  sort: 'rating'
});
const url = 'https://api.example.com/search?' + params.toString();
// https://api.example.com/search?q=coffee+shops+%26+cafes&city=New+York&sort=rating

Note: URLSearchParams encodes spaces as + (form-style), not %20. Both are valid for query strings; most servers accept either. If you need %20 specifically, use encodeURIComponent() manually and join with &.

Decoding URL-Encoded Strings in JavaScript

The reverse functions are decodeURIComponent() and decodeURI(). Use decodeURIComponent() when reading a query parameter value:

const raw = 'hello%20world%20%26%20more';
decodeURIComponent(raw);
// Returns: 'hello world & more'

For quick encoding/decoding without writing any code, use the Mongoose URL Encoder — paste any string and click Encode or Decode.

Frequently Asked Questions

Why does encodeURIComponent encode the apostrophe but not the exclamation mark?

Both ! and ' are in the list of characters encodeURIComponent leaves unencoded — they're considered "unreserved" in older RFCs. If you need to encode them too (for strict compliance), replace them manually after encoding.

Can I use encodeURIComponent on a full URL?

Technically yes, but the output won't be a valid URL anymore — the slashes, colons, and question marks will all be encoded. The result is useful only if you're passing the URL itself as a parameter value inside another URL.

How do I decode a query parameter value in JavaScript?

Use decodeURIComponent(). For example: decodeURIComponent(new URLSearchParams(window.location.search).get("q")) reads and decodes the "q" parameter from the current page URL.

Does JavaScript have a built-in way to build URLs safely?

Yes — the URL and URLSearchParams APIs handle encoding for you. URLSearchParams.set() encodes values automatically, and URL.searchParams gives you a typed interface for reading and writing query parameters.