encodeURIComponent vs encodeURI: What's the Difference?

Published on · 775 words

Want to follow along with this guide? Open the free URL encoder & decoder and try encoding URLs, parsing components, and editing query parameters interactively.

JavaScript provides two built-in functions for URL encoding: encodeURI and encodeURIComponent. While they may seem interchangeable, they handle different sets of characters and serve different purposes. Using the wrong one is one of the most common sources of URL-related bugs in web applications.

This guide breaks down exactly which characters each function encodes, when to use each one, and practical examples that illustrate the difference. By the end, you will never confuse them again — and you will know how our free URL encoder tool lets you switch between both modes instantly.

Which Characters Does Each Function Encode?

encodeURI is designed to encode a complete URL. It preserves characters that have structural meaning in URLs: : ? # [ ] @ ! $ & ' ( ) * + , ; = / and the unreserved characters A-Z a-z 0-9 - _ . ~. It only encodes spaces, non-ASCII characters, and a few other unsafe characters like < > { } | \ ^ `.

encodeURIComponent encodes everything that encodeURI does, plus all characters with special meaning in URLs: ; , / ? : @ & = + $ #. This makes it suitable for encoding individual components (like query parameter values) where these characters should be treated as data, not as URL delimiters.

When to Use Each Function

The rule is simple: use encodeURI when you have a complete URL that needs encoding (for example, a URL with spaces or non-ASCII characters in the path). Use encodeURIComponent when you are encoding a value that will be placed inside a URL component, such as a query parameter value or a path segment.

  • encodeURI: Use for complete URLs — 'https://example.com/path with spaces/page'. It preserves the URL structure while encoding unsafe characters.
  • encodeURIComponent: Use for query parameter values — 'https://example.com/search?q=' + encodeURIComponent('hello world & more'). It encodes &, =, and other characters that would break the query string.
  • encodeURIComponent: Use for path segments — 'https://example.com/api/' + encodeURIComponent('user/name'). It encodes the / so it becomes part of the data, not a path separator.
  • Never use encodeURI for query values — it does not encode & or =, so your query string will be silently corrupted.
  • Never use encodeURIComponent on a complete URL — it will encode : / ? and other structural characters, breaking the URL entirely.

Common Mistakes and How to Avoid Them

The most common mistake is using encodeURI for query parameter values. Since encodeURI does not encode & and =, a value like 'foo=bar&baz=qux' would be interpreted as two separate parameters instead of one value. Always use encodeURIComponent for values.

Another frequent error is double-encoding. If you encode a value with encodeURIComponent and then pass the entire URL through encodeURI, the percent signs from the first encoding get encoded again, producing %25 instead of %. This results in the server receiving the literal string '%20' instead of a space. Encode once, at the right level.

A third mistake is manually building query strings with string concatenation instead of using URLSearchParams. The URLSearchParams API handles encoding automatically and produces correctly formatted query strings without the risk of encoding errors. Our URL encoder tool also provides a visual query string editor that handles encoding behind the scenes.

Frequently Asked Questions

What is the main difference between encodeURIComponent and encodeURI?▼
encodeURI preserves URL-structural characters like :/?#[]@&=+$, while encodeURIComponent encodes all of them. Use encodeURI for complete URLs and encodeURIComponent for individual query parameter values or path segments.
When should I use encodeURIComponent?▼
Use encodeURIComponent whenever you are encoding a value that will be placed inside a URL component — typically a query parameter value or a dynamic path segment. It ensures that characters like &, =, ?, and / are encoded and do not break the URL structure.
When should I use encodeURI?▼
Use encodeURI when you have a complete URL that contains characters needing encoding (like spaces or non-ASCII characters) but you want to preserve the URL structure. It encodes unsafe characters while keeping :/?#[]@&=+$ intact.
What happens if I use encodeURI on a query parameter value?▼
encodeURI does not encode &, =, ?, and # characters. If your value contains any of these, they will be interpreted as URL delimiters instead of data, silently corrupting your query string. Always use encodeURIComponent for query values.
What is double-encoding and how do I avoid it?▼
Double-encoding happens when you encode a value and then encode the result again. The percent signs from the first encoding (%20) get encoded to %2520. To avoid it, encode each value exactly once at the point of URL construction, and never pass an already-encoded URL through an encoding function again.

Try it now — free, private, and instant

Encode or decode URLs, parse URL components, and edit query string parameters as an interactive table.

Launch the URL Encoder