encodeURIComponent()

For one VALUE inside a URL — a query parameter, a path segment. encodeURI is for a whole URL and deliberately leaves the structural characters intact, which makes it the wrong choice for values.

Global functionES3 (1999)Live demo
Common call
encodeURIComponent(value)
Returns
a percent-encoded string
Replaces
the deprecated escape()
Watch out
it does NOT escape ! ' ( ) * — and a lone surrogate throws
encodeURIComponent(stringstring — The text to escape. Non-strings are converted first. A lone surrogate — from slicing an emoji in half — throws URIError.type: string · required)
→ string

Demo

Live evaluation
Try:
Inputs
sstringtext to encode
Output
[encodeURIComponent('a b&c=d'), encodeURI('a b&c=d')]
['a%20b%26c%3Dd', 'a%20b&c=d']

The pair is [encodeURIComponent, encodeURI]. The first case is the decision in one line: for the text 'a b&c=d', encodeURIComponent escapes the & and = because inside a single value they would be mistaken for structure, while encodeURI leaves them because in a whole URL that is exactly what they are. The second case shows the mirror image — encodeURI keeps a URL usable, encodeURIComponent destroys it by escaping the slashes and colon. Accented characters become UTF-8 byte sequences in both. Note the fourth case: several punctuation characters are NOT escaped by either.

Parameters

NameTypeRequiredDescription
stringstringyesThe text to escape. Non-strings are converted first. A lone surrogate — from slicing an emoji in half — throws URIError.

Return value

string — The string with every character escaped except A–Z a–z 0–9 and - _ . ! ~ * ' ( ). Non-ASCII characters become UTF-8 percent sequences.

Common patterns

Build a query string
Better still, let URLSearchParams do it.
const q = new URLSearchParams({name: value}).toString();
Escape one path segment
A value that might contain a slash.
const url = `/users/${encodeURIComponent(id)}`;
Fix a URL that has spaces
This is what encodeURI is for.
const safe = encodeURI(urlWithSpaces);

Examples

1. A value
encodeURIComponent('a b&c=d')
Returns
'a%20b%26c%3Dd'
2. A whole URL
encodeURI('a b&c=d')
Returns
'a%20b&c=d'
3. It destroys a URL
encodeURIComponent('https://x.com/a')
Returns
'https%3A%2F%2Fx.com%2Fa'
4. UTF-8 for non-ASCII
encodeURIComponent('é')
Returns
'%C3%A9'
5. !'()* survive
encodeURIComponent("!'()*")
Returns
"!'()*"
6. A lone surrogate throws
encodeURIComponent('\ud83d')
Returns
URIError: URI malformed

Pitfalls

1. Using encodeURI for a value
The classic mix-up. encodeURI leaves & = ? # / : alone, so a value containing any of them silently changes the MEANING of the URL — a value with an & becomes two parameters. Values always want encodeURIComponent.
Injects a parameter
'?q=' + encodeURI('a&admin=1')
'?q=a&admin=1'
Escaped
'?q=' + encodeURIComponent('a&admin=1')
'?q=a%26admin%3D1'
2. It leaves ! ' ( ) * unescaped
Those five are legal in a URI but not in every context that consumes one — some older servers and OAuth signature schemes require them escaped. If a signature mismatches, this is often why.
Not escaped
encodeURIComponent("it's")
"it's"
Escape them too
encodeURIComponent("it's").replace(/[!'()*]/g, c => '%' + c.charCodeAt(0).toString(16).toUpperCase())
'it%27s'
3. A lone surrogate throws URIError
There is no UTF-8 encoding for half a surrogate pair, so a string truncated through an emoji crashes here rather than producing mangled output. That makes this function a common place for a slice bug to finally surface.
Throws
encodeURIComponent('\u{1F600}abc'.slice(0, 1))
URIError: URI malformed
Repair first
encodeURIComponent('\u{1F600}abc'.slice(0, 1).toWellFormed())
'%EF%BF%BD'
4. It does not encode a space as +
It produces %20. The + convention belongs to application/x-www-form-urlencoded form bodies, not to URLs generally — so a server expecting form encoding may not decode %20 the way you assume. URLSearchParams handles the distinction.
Percent form
encodeURIComponent('a b')
'a%20b'
Form encoding
new URLSearchParams({q: 'a b'}).toString()
'q=a+b'

When to use

Use it
  • Escaping one query-parameter value
  • Escaping a path segment that may contain reserved characters
  • Anywhere a value is concatenated into a URL by hand
Reach for something else
  • Building a whole query string → URLSearchParams
  • Fixing an existing URL with spaces → encodeURI
  • HTML escaping → this is not an HTML escaper
  • escape() → deprecated and wrong for non-Latin-1

Notes

Complexity
O(n) in the length of the string
Return
A new string; the input is unchanged
CPython impl
V8: Builtins-global-encodeuricomponent
Memory
Allocates the result string
Thread-safe
Single-threaded

FAQ

Component for a VALUE going into a URL; encodeURI for a whole URL that needs tidying. The test: if the text could legitimately contain a & or / that is data rather than structure, you need encodeURIComponent.

encodeURIComponent(value);   // one piece
encodeURI(wholeUrl);         // an entire URL

History

ES1
escape and unescape shipped, using Latin-1 and a non-standard %uXXXX form.
ES3
encodeURI and encodeURIComponent added with proper UTF-8 encoding; escape deprecated.