uri

A string to be encoded as a URI.

A new string representing the provided string encoded as a URI.

URIError

Thrown ifuri contains alone surrogate.

encodeURI() is a function property of the global object.

TheencodeURI() function escapes characters by UTF-8 code units, with each octet encoded in the format%XX, left-padded with 0 if necessary. Because lone surrogates in UTF-16 do not encode any valid Unicode character, they causeencodeURI() to throw aURIError.

encodeURI() escapes all charactersexcept:

A–Z a–z 0–9 - _ . ! ~ * ' ( ); / ? : @ & = + $ , #

The characters on the second line are characters that may be part of the URI syntax, and are only escaped byencodeURIComponent(). BothencodeURI() andencodeURIComponent() do not encode the characters-.!~*'(), known as "unreserved marks", which do not have a reserved purpose but are allowed in a URI "as is". (SeeRFC2396)

TheencodeURI() function does not encode characters that have special meaning (reserved characters) for a URI. The following example shows all the parts that a URI can possibly contain. Note how certain characters are used to signify special meaning:

http://username:password@www.example.com:80/path/to/file.php?foo=316&bar=this+has+spaces#anchor

encodeURI, as the name implies, is used to encode a URL as a whole, assuming it is already well-formed. If you want to dynamically assemble string values into a URL, you probably want to useencodeURIComponent() on each dynamic segment instead, to avoid URL syntax characters in unwanted places.

const name = "Ben & Jerry's";// This is bad:const link = encodeURI(`https://example.com/?choice=${name}`); // "https://example.com/?choice=Ben%20&%20Jerry's"console.log([...new URL(link).searchParams]); // [['choice', 'Ben '], [" Jerry's", '']// Instead:const link = encodeURI(  `https://example.com/?choice=${encodeURIComponent(name)}`,);// "https://example.com/?choice=Ben%2520%2526%2520Jerry's"console.log([...new URL(link).searchParams]); // [['choice', "Ben%20%26%20Jerry's"]]

encodeURI() differs fromencodeURIComponent() as follows:

const set1 = ";/?:@&=+$,#"; // Reserved Charactersconst set2 = "-.!~*'()"; // Unreserved Marksconst set3 = "ABC abc 123"; // Alphanumeric Characters + Spaceconsole.log(encodeURI(set1)); // ;/?:@&=+$,#console.log(encodeURI(set2)); // -.!~*'()console.log(encodeURI(set3)); // ABC%20abc%20123 (the space gets encoded as %20)console.log(encodeURIComponent(set1)); // %3B%2C%2F%3F%3A%40%26%3D%2B%24%23console.log(encodeURIComponent(set2)); // -.!~*'()console.log(encodeURIComponent(set3)); // ABC%20abc%20123 (the space gets encoded as %20)

AURIError will be thrown if one attempts to encode a surrogate which is not part of a high-low pair. For example:

// High-low pair OKencodeURI("\uD800\uDFFF"); // "%F0%90%8F%BF"// Lone high-surrogate code unit throws "URIError: malformed URI sequence"encodeURI("\uD800");// Lone low-surrogate code unit throws "URIError: malformed URI sequence"encodeURI("\uDFFF");

You can useString.prototype.toWellFormed(), which replaces lone surrogates with the Unicode replacement character (U+FFFD), to avoid this error. You can also useString.prototype.isWellFormed() to check if a string contains lone surrogates before passing it toencodeURI().

The more recentRFC3986 makes square brackets reserved (forIPv6) and thus not encoded when forming something which could be part of a URL (such as a host). It also reserves !, ', (, ), and *, even though these characters have no formalized URI delimiting uses. The following function encodes a string for RFC3986-compliant URL format.

function encodeRFC3986URI(str) {  return encodeURI(str)    .replace(/%5B/g, "[")    .replace(/%5D/g, "]")    .replace(      /[!'()*]/g,      (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,    );}

• decodeURI()
• encodeURIComponent()
• decodeURIComponent()