JavaScript encodeURI() Function

Beginner
6 min read
Updated: Nov 2026
3 examples
Global function

Definition

encodeURI() makes a whole web address safe to use. It replaces characters that are not allowed in a URL, such as spaces and letters like e with an accent, with percent codes like %20.

It leaves the parts that give a URL its structure alone: : / ? # & = and a few more. That is the key difference from encodeURIComponent(), which encodes those too.

Remember
encodeURI(uri);

uri     -> a complete URL (or a text that looks like one)
returns -> a new string with unsafe characters as %XX codes

NOT encoded: A-Z a-z 0-9 - _ . ! ~ * ' ( )
             ; , / ? : @ & = + $ #
Encoded:     spaces, quotes, < > { } | and non-English letters

Syntax

Call encodeURI() by name and give it a full URL as text. It returns the encoded text and does not change the original.

JavaScript
encodeURI(uri);
CallWhat it does
encodeURI("https://example.com/my file.pdf")The space becomes %20. Result: "https://example.com/my%20file.pdf".
encodeURI("a?b=1&c=2")Nothing changes, because ? = & are part of the URL structure.
encodeURI("caf\u00e9")The accented letter becomes its UTF-8 bytes. Result: "caf%C3%A9".

Built into JavaScript (ES3). It is a global function, so you call it by name with no import. See also: encodeURIComponent(), decodeURI() and decodeURIComponent().

Library declarations
JavaScript
// Global function (ES3)
encodeURI(uri)

// returns a string
// throws URIError for a lone surrogate (broken Unicode)

Parameters

ParameterDescription
uriThe text to encode, normally a complete URL. A value that is not text is converted to text first.

Return Value

Return ValueDescription
A stringA copy of the text where every character that is not allowed in a URL is replaced by one to four %XX codes (the UTF-8 bytes of that character).
URIError (thrown)The text contains a lone surrogate, which is half of an emoji or other character outside the basic range with the other half missing.

JavaScript Examples

Example 1 — Encode a URL with Spaces

A URL with spaces is not valid. encodeURI() fixes the spaces and keeps everything else in place.

JavaScript
const url = "https://example.com/my files/report 2026.pdf?name=Mia Lee&city=New York";

console.log(encodeURI(url));
Try It Yourself

How It Works

  1. Spaces become %20. Every space in the path and in the query string is replaced by %20.
  2. The structure stays. https://, the slashes, the ?, the = and the & are not changed, so the result is still a working address.

Example 2 — See What encodeURI() Keeps and Changes

Some characters are part of how a URL works, so they stay. Others are not allowed, so they change.

JavaScript
console.log("Kept: " + encodeURI("https://example.com:8080/path?x=1&y=2#top"));
console.log("Kept: " + encodeURI(";,/?:@&=+$#"));
console.log("Kept: " + encodeURI("A-Za-z0-9-_.!~*'()"));
console.log("Changed: " + encodeURI('<>"{}|'));
console.log("Changed: " + encodeURI("50% off"));
console.log("Changed: " + encodeURI("caf\u00e9"));
console.log("Changed: " + encodeURI("\u20ac"));
Try It Yourself

How It Works

  1. Reserved characters stay. : / ? # & = + $ , ; @ are the building blocks of a URL, so encodeURI() never touches them.
  2. Letters, digits and a few symbols stay. The third line shows that A-Z a-z 0-9 - _ . ! ~ * ' ( ) are never encoded.
  3. Unsafe characters change. Angle brackets, quotes, braces and the bar become %3C %3E %22 %7B %7D %7C. A % becomes %25.
  4. Other languages and symbols. "\u00e9" (e with an accent) is written as two bytes, %C3%A9. The euro sign needs three bytes, %E2%82%AC.

Example 3 — Do Not Encode Twice and Handle Errors

Encoding text that is already encoded breaks it. Broken Unicode throws an error you can catch.

JavaScript
const once = encodeURI("my file.txt");
const twice = encodeURI(once);

console.log("Once: " + once);
console.log("Twice: " + twice);
console.log("Decoded twice: " + decodeURI(decodeURI(twice)));

try {
  encodeURI("\uD800");
} catch (err) {
  console.log("Lone surrogate: " + err.name);
}
Try It Yourself

How It Works

  1. First pass. The space becomes %20.
  2. Second pass. The % of %20 is encoded again as %25, so you get %2520. A server that decodes once will see my%20file.txt instead of my file.txt.
  3. Broken Unicode. "\uD800" is half of a pair of codes and cannot be turned into bytes. encodeURI() throws a URIError, and the catch block prints its name.

Browser & Runtime Support

encodeURI() arrived with ES3 and has worked in every browser for a very long time. Every Node.js version has it too.

✓ ES3 · Works everywhere

encodeURI()

Supported in all browsers, including old ones, and in Node.js, Deno and Bun.

ES3 Standard since
Google Chrome All versions · Desktop & Mobile
Full support
Microsoft Edge All versions · Chromium & Legacy
Full support
Mozilla Firefox All versions · Desktop & Mobile
Full support
Apple Safari All versions · macOS & iOS
Full support
Opera All versions
Full support
Samsung Internet All versions · Android
Full support
Android WebView All versions
Full support
Node.js All versions · Server runtime
Supported
Deno All versions · JavaScript runtime
Supported
Bun All versions · JavaScript runtime
Supported
Internet Explorer All versions
Full support
encodeURI() Excellent

Bottom line: Safe to use anywhere. Even Internet Explorer has it. For new code you can also build URLs with the URL object, which encodes parts for you.

Frequently Asked Questions

It turns a complete URL into a safe text by replacing characters that are not allowed, such as spaces and non-English letters, with percent codes like %20. It keeps characters that give the URL its structure, such as : / ? # & and =.
encodeURI() is for a whole URL and keeps the structure characters : / ? # & = + $ , ; @. encodeURIComponent() is for one piece of a URL, such as a search word, and encodes those characters too. Use encodeURIComponent() for values you put inside a query string.
A URL cannot contain a space. %20 is the percent code for the space character (ASCII code 32 in hexadecimal is 20). Forms sometimes use + for a space, but encodeURI() always uses %20.
Because % is the start of every percent code, a plain % in the text must be written as %25. That is also why encoding already encoded text breaks it: %20 becomes %2520.
When the text contains a lone surrogate, which is half of a character from outside the basic range (such as an emoji) without its other half. Valid text, including whole emoji, never throws.

Next: encodeURIComponent()

Learn how to encode a single value, such as a search word, so it can sit safely inside a URL.

encodeURIComponent() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

13 people found this page helpful