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);
Call
What 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".
// Global function (ES3)
encodeURIComponent(uriComponent)
// returns a string
// throws URIError for a lone surrogate (broken Unicode)
Parameters
Parameter
Description
value
The 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 Value
Description
A string
A 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.
Every special character is encoded. The space becomes %20, & becomes %26, / becomes %2F, % becomes %25 and ? becomes %3F.
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.
Loop over the keys.Object.keys(params) gives name, city and note.
Encode both sides. Each key and each value goes through encodeURIComponent(), and they are joined with =.
Join with &. The & that separates parameters is added after encoding, so the & inside "50% off & more" is safely written as %26.
Other languages. The letter "\u00e3" in S\u00e3o becomes the two bytes %C3%A3.
Compatibility
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.
ES3Standard since
Google ChromeAll versions · Desktop & Mobile
Full support
Microsoft EdgeAll versions · Chromium & Legacy
Full support
Mozilla FirefoxAll versions · Desktop & Mobile
Full support
Apple SafariAll versions · macOS & iOS
Full support
OperaAll versions
Full support
Samsung InternetAll versions · Android
Full support
Android WebViewAll versions
Full support
Node.jsAll versions · Server runtime
Supported
DenoAll versions · JavaScript runtime
Supported
BunAll versions · JavaScript runtime
Supported
Internet ExplorerAll 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.