encodeURI vs encodeURIComponent

The short answer

Use encodeURI() when you already have a structured URI and want to encode text without hiding its main separators. Use encodeURIComponent() when you are encoding one value inside that URI, such as a query parameter, path segment, or fragment value.

The distinction is about ownership of delimiters. A full URI uses characters such as :, /, ?, &, and = to separate parts. A component should treat those characters as data and escape them.

What each function preserves

Both functions accept a JavaScript string and return a percent-encoded string. They differ in which reserved URI characters remain available for structure.

encodeURI example: preserve a structured URI

const uri = "https://api.demo.invalid/search?q=red apples&lang=en";
const encoded = encodeURI(uri);
// https://api.demo.invalid/search?q=red%20apples&lang=en

The spaces are encoded, but the scheme, host, path, and query separators remain recognizable as URI structure. This does not validate the host or fetch the resource.

encodeURIComponent example: encode one value

const value = "red apples & tea";
const encoded = encodeURIComponent(value);
// red%20apples%20%26%20tea

The ampersand is data in this value, so it is escaped. If it were left raw while building a query string, a server could interpret it as a second parameter.

Encoding query parameters safely

Build a query string by encoding each name and value separately, then join the pairs with &. Do not call encodeURIComponent() on the complete URL after adding its structure.

const params = [
  ['q', 'red apples & tea'],
  ['lang', 'en'],
];
const query = params
  .map(([name, value]) =>
    `${encodeURIComponent(name)}=${encodeURIComponent(value)}`,
  )
  .join('&');

For larger applications, URLSearchParams can manage names, values, repeated parameters, and serialization. The URL Parser can help inspect the resulting components.

Common mistakes

• Encoding the whole URL as a component: this escapes slashes and separators, so the result is no longer a normally structured URL.
• Leaving a value raw: an ampersand, equals sign, or question mark inside user data can change the query structure.
• Double-encoding: encoding already escaped text turns percent signs into %25.
• Confusing encoding with validation: neither API checks reachability, scheme safety, server expectations, or authorization.
• Building URLs by string concatenation: use URL and URLSearchParams when you need structured mutation.

Use Orbilyra's URL Encoder / Decoder for a direct local encoding check, and review URL Encoding Explained for broader percent-encoding concepts.

When to use each API

Neither function is a security boundary. Treat untrusted URLs as data, validate according to your application, and avoid navigating to schemes or destinations you do not intend to allow.