encodeURI()

encodeURI(uri)

The encodeURI() function encodes a Uniform Resource Identifier (URI) by replacing certain characters with escape sequences. It encodes all characters except those that have special meaning in URIs.

Syntax

encodeURI(uri)

Parameters

Parameter	Type	Description
uri	string	The complete URI to encode.

Return Value

A new encoded string.

The function receives a single string argument and returns its percent-encoded form. Characters that are safe in a URI pass through unchanged, while everything else is converted. The key behavior to understand is which characters the function treats as safe and which it encodes.

What encodeURI() does not encode

This function preserves certain characters that have special meaning in URIs:

encodeURI("ABCabc0123-_.~");
// "ABCabc0123-_.~" - unreserved characters preserved

encodeURI("hello world");
// "hello%20world" - spaces encoded

encodeURI("a/b?c=d");
// "a/b?c=d" - slashes, question marks preserved

encodeURI("test&foo=bar");
// "test&foo=bar" - ampersand preserved

The examples above show which characters survive encoding and which get replaced. When you apply encodeURI() to a full URL string, the function leaves the structural characters intact — slashes, colons, and query delimiters pass through — while encoding the parts that would break the URL if left as literals.

Examples

Encoding full URLs

encodeURI("https://example.com/my page");
// "https://example.com/my%20page"

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

Full URLs with spaces or non-ASCII characters in the path are the most common use case for encodeURI(). The function also handles Unicode characters by converting each non-ASCII code point to its UTF-8 byte sequence and then percent-encoding each byte, producing sequences like %E6%95%99 for CJK characters.

Encoding Unicode characters

encodeURI("JavaScript教程");
// "JavaScript%E6%95%99%E7%A8%8B"

encodeURI("café");
// "caf%C3%A9"

Unicode encoding works the same way for any non-ASCII text. When you are building query strings, however, you often need a different approach — encoding only the parameter values while keeping the = and & delimiters intact. For query string values without special URI characters, encodeURI() handles the encoding without breaking the structure.

Encoding query string components

When building query strings, you often need to encode individual components:

const name = "John Doe";
const query = "name=" + encodeURI(name);
// "name=John%20Doe"

Encoding query values with encodeURI() works when the values contain only spaces and simple characters, but it does not encode characters like ?, =, and & that carry structural meaning in a URI. When those characters appear in a value, you need the stricter approach that encodeURIComponent() provides. The two functions complement each other, and choosing the wrong one can silently break a URL.

When to Use encodeURI vs encodeURIComponent

Use encodeURI() when encoding a complete URI:

encodeURI("https://example.com/path");
// "https://example.com/path" - already valid URI

encodeURI("https://example.com/path name");
// "https://example.com/path%20name" - spaces encoded

The encodeURI() example shows how it preserves URL structure. The encodeURIComponent() example below demonstrates the opposite — it encodes every special character, including the structural ones. This is exactly what you want for individual query parameter values, but applying it to a full URL string destroys the protocol, slashes, and query syntax.

Use encodeURIComponent() when encoding a URI component (like a query parameter value):

encodeURIComponent("?q=hello");
// "%3Fq%3Dhello" - encodes everything including ? and =

// Wrong for full URLs - breaks the URL structure
encodeURIComponent("https://example.com");
// "https%3A%2F%2Fexample.com" - breaks the protocol!

Choosing the right encoding function prevents structural breakage in URLs. An equally common mistake happens when you apply encoding more than once. Double-encoding is subtle because it produces valid output that looks almost correct, but the resulting percent signs themselves get encoded, changing the decoded value.

Common Mistakes

Encoding an already encoded string

// Don't double-encode
const encoded = encodeURI("hello world");
// "hello%20world"

encodeURI(encoded);
// "hello%2520world" - the % becomes %25!

Double-encoding is a mistake you make when you encode a string that was already encoded. Another common pitfall is using encodeURI() on user input that will become part of a query parameter value. Since encodeURI() leaves & and = untouched, a user-supplied value containing those characters can inject additional parameters into the query string. When handling user input bound for query strings, always use encodeURIComponent() instead.

Using encodeURI for user input

// For form data that will be sent as query parameters
const userInput = document.getElementById("search").value;
const param = encodeURIComponent(userInput);
const url = "/search?q=" + param;

How encodeURI() works

encodeURI() scans the string character by character. For each character, if it falls into the set of characters that are safe in a URI (letters, digits, and specific reserved/unreserved symbols), it leaves it unchanged. For all other characters — including spaces, non-ASCII Unicode, and certain punctuation — it converts the character to its UTF-8 byte sequence and percent-encodes each byte as %XX. The result is a string where every non-safe character has been replaced by its percent-encoded equivalent.

What encodeURI() leaves unchanged

encodeURI() preserves 82 characters: the 26 uppercase and 26 lowercase ASCII letters, the 10 digits, and the following symbols: -, _, ., !, ~, *, ', (, ) (unreserved characters), plus ;, ,, /, ?, :, @, &, =, +, $, # (reserved URI characters that have structural meaning). Everything else — spaces, non-ASCII characters, and other symbols — is percent-encoded.

Error handling

encodeURI() throws a URIError if the string contains a lone surrogate (half of a surrogate pair). This can happen with strings constructed from low-level code that creates invalid UTF-16. Well-formed JavaScript strings from normal sources do not trigger this error.

Modern alternative: URL constructor

For most URL-building tasks in modern JavaScript, the URL constructor is cleaner than manual encodeURI() calls. It handles encoding automatically and gives you structured access to each URL component:

const url = new URL('https://example.com');
url.pathname = '/search';
url.searchParams.set('q', 'hello world');
url.href; // "https://example.com/search?q=hello+world"

See Also

• decodeURI() — Decode a URI encoded by encodeURI
• encodeURIComponent() — Encode URI components with stricter encoding
• decodeURIComponent() — Decode any URI component fully