encodeURI vs encodeURIComponent: which one to use

Short answer

Use encodeURIComponent for one value that will be inserted into a path, query, or fragment. Use encodeURI only when you already have a complete URL and need to preserve its structural delimiters. The safer general approach is to build addresses with URL and URLSearchParams instead of concatenating pre-encoded strings.

The difference is what remains unescaped

A URL has structure: https://, path slashes, ?, pairs separated by &, assignments with =, and a fragment after #. encodeURI keeps many of these characters because it assumes they belong to a complete address.

encodeURIComponent assumes its input is one data item. It encodes characters such as ?, &, =, and / that could change the surrounding structure.

The URL encoder lets you compare component and complete-URL modes locally in the browser.

Query parameter example

Suppose the value for q is bread & oil. The intended URL is:

https://example.test/search?q=bread%20%26%20oil

Applying encodeURI only to the value leaves & visible, so a server may read it as the start of another parameter. encodeURIComponent produces %26, keeping the ampersand inside the value.

A clearer construction is:

const url = new URL('https://example.test/search');
url.searchParams.set('q', 'bread & oil');

The API then maintains the boundary between data and structure.

Complete URL example

For https://example.test/a b?q=café#part 1, encodeURI preserves the scheme, host, /, ?, =, and # while encoding spaces and disallowed characters. encodeURIComponent instead turns the whole address into a single value. That result is useful when embedding one URL inside another parameter, but not as a direct navigation URL.

Even encodeURI does not prove that an address has an allowed host or scheme. Parsing with new URL() makes components available for explicit policy checks.

Paths and fragments contain components too

A user-controlled path segment should be encoded as a component. If the value is report/2026, preserving / creates two path segments. As one segment, it should become report%2F2026.

The same reasoning applies to a fragment or parameter name. “Component” does not mean only a query value; it means data that must not introduce a delimiter in its insertion context.

Common mistakes

• Applying encodeURIComponent to a complete URL and then trying to navigate to the result.
• Using encodeURI for a value containing &, #, or =.
• Encoding text that already contains %HH, which creates %25HH.
• Decoding an entire URL with decodeURIComponent before separating its parameters, turning %26 into a delimiter too early.
• Expecting either function to produce HTML form encoding, where a space is commonly written as +.

The precise functions and character sets are specified by ECMAScript.

Practical rule

Work from the smallest unit: keep values unencoded inside the program, use URLSearchParams for queries, and encode a segment only at the boundary where it is inserted. When receiving a complete URL, parse its parts rather than blindly decoding and re-encoding it. This separation reduces double encoding and prevents user-controlled data from accidentally becoming URL structure.