JavaScript encodeURIComponent() Function

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

Definition

encodeURIComponent() makes one piece of text safe to use inside a URL, such as a search word, a name or a file name. It replaces almost every special character with a percent code like %26.

It even encodes / ? # & = +, so the text cannot be mistaken for part of the URL structure. That makes it the right tool for query string values. For a whole URL, use encodeURI() instead.

Remember
encodeURIComponent(value);

value   -> one piece of text (a query value, a name, a path part)
returns -> a new string with unsafe characters as %XX codes

NOT encoded: A-Z a-z 0-9 - _ . ! ~ * ' ( )
Encoded:     everything else, including ; , / ? : @ & = + $ #

Syntax

Call encodeURIComponent() by name and give it the value. It returns the encoded text and does not change the original.

JavaScript
encodeURIComponent(value);
CallWhat it does
encodeURIComponent("rock & roll")The space and the ampersand are encoded. Result: "rock%20%26%20roll".
encodeURIComponent("a/b?c=d")Slash, question mark and equals sign are encoded. Result: "a%2Fb%3Fc%3Dd".
encodeURIComponent("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: encodeURI(), decodeURIComponent() and decodeURI().

Library declarations
JavaScript
// Global function (ES3)
encodeURIComponent(uriComponent)

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

Parameters

ParameterDescription
valueThe text to encode. A value that is not text is converted to text first, so a number or a boolean also works. undefined becomes the text "undefined", so check for it before you encode.

Return Value

Return ValueDescription
A stringA copy of the text where every character except A-Z a-z 0-9 - _ . ! ~ * ' ( ) 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 Query Value

A search word can contain spaces, an ampersand, a slash and a question mark. encodeURIComponent() makes all of them safe.

JavaScript
const search = "rock & roll / 100% fun?";
const encoded = encodeURIComponent(search);

console.log(encoded);
console.log("https://example.com/search?q=" + encoded);
Try It Yourself

How It Works

  1. Every special character is encoded. The space becomes %20, & becomes %26, / becomes %2F, % becomes %25 and ? becomes %3F.
  2. Safe inside a URL. The & in the search word can no longer be mistaken for the start of a second parameter, so the server reads the whole phrase as the value of q.

Example 2 — Compare with encodeURI()

The same text through both functions shows which characters each one protects.

JavaScript
const text = "a/b?c=d&e#f";

console.log("encodeURI: " + encodeURI(text));
console.log("encodeURIComponent: " + encodeURIComponent(text));

console.log("Plus sign: " + encodeURIComponent("1+1=2"));
console.log("Kept: " + encodeURIComponent("A-Za-z0-9-_.!~*'()"));
Try It Yourself

How It Works

  1. encodeURI() keeps the structure. It leaves / ? = & # alone, because in a whole URL they have a job to do.
  2. encodeURIComponent() encodes them. They become %2F %3F %3D %26 %23, so the text is treated as plain data.
  3. The plus sign. A + in a URL can mean a space, so it is encoded as %2B. Without that, your plus would be read as a space.
  4. A few symbols stay. Letters, digits and - _ . ! ~ * ' ( ) are never encoded.

Example 3 — Build a Query String

Encode each key and each value on its own, then join them with &. This also handles non-English letters.

JavaScript
const params = {
  name: "Mia Lee",
  city: "S\u00e3o Paulo",
  note: "50% off & more"
};

const query = Object.keys(params)
  .map(key => encodeURIComponent(key) + "=" + encodeURIComponent(params[key]))
  .join("&");

console.log(query);
console.log("https://example.com/order?" + query);
Try It Yourself

How It Works

  1. Loop over the keys. Object.keys(params) gives name, city and note.
  2. Encode both sides. Each key and each value goes through encodeURIComponent(), and they are joined with =.
  3. Join with &. The & that separates parameters is added after encoding, so the & inside "50% off & more" is safely written as %26.
  4. Other languages. The letter "\u00e3" in S\u00e3o becomes the two bytes %C3%A3.

Browser & Runtime Support

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

✓ ES3 · Works everywhere

encodeURIComponent()

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
encodeURIComponent() Excellent

Bottom line: Safe to use anywhere. For new code, URLSearchParams can build and encode a whole query string for you, using + for spaces.

Frequently Asked Questions

It encodes one piece of text so it is safe inside a URL. Every character except letters, digits and - _ . ! ~ * ' ( ) is replaced by percent codes, so a value like "rock & roll" becomes "rock%20%26%20roll".
encodeURIComponent() encodes everything except letters, digits and a few symbols, including / ? # & = and +. encodeURI() keeps those, because it is meant for a complete URL. Use encodeURIComponent() for values (query parameters, path parts) and encodeURI() for a whole address.
Encode the variable and join it to the URL: "https://example.com/search?q=" + encodeURIComponent(word). This stops spaces, ampersands and other special characters in the word from breaking the URL.
In a query string a plain + often means a space. To send a real plus sign, it must be written as %2B. encodeURIComponent() does this for you.
No. It would also encode https://, the colons and every slash, and the result would not work as an address. Encode each value separately and build the URL around them, or use encodeURI() for a whole URL.

Next: escape()

Meet the old escape() function, why it is deprecated, and what to use instead.

escape() 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.

17 people found this page helpful