Developer Guide
URL Encoding in JavaScript
encodeURIComponent encodes a query value; encodeURI leaves :/?# intact. URLSearchParams uses + for spaces. Decode once. Unicode becomes UTF-8 percent bytes.
Percent-encoding is how a URL carries characters that would otherwise be syntax. A space becomes %20. An ampersand in a value becomes %26 so it does not start the next pair. JavaScript gives you two functions that look interchangeable and are not: encodeURIComponent for a single value or path segment, encodeURI for a whole URL whose structure you already trust.
/tools/url-encoder exposes both. hello world → hello%20world in either mode, because space is not a reserved delimiter. encodeURIComponent('name=John&age=30') → name%3DJohn%26age%3D30 — that string is one value, not two query pairs. encodeURI keeps : / ? #. This page is the JavaScript API, including URLSearchParams and UTF-8 bytes for नमस्ते.
encodeURIComponent for values
encodeURIComponent encodes everything except A–Z a–z 0–9 - _ . ~ (and a few historical extras). That is the unreserved set. Use it on each query value, and on a path segment you did not generate yourself.
Build URLs by encoding pieces, then joining reserved punctuation you mean as syntax: 'https://example.com/search?q=' + encodeURIComponent(q). Do not concatenate raw user text. /tools/url-encoder in encodeURIComponent mode is the same function the engine ships.
encodeURIComponent('hello world');
// 'hello%20world'
encodeURIComponent('name=John&age=30');
// 'name%3DJohn%26age%3D30'
const q = 'name=John&age=30';
const url = 'https://example.com/search?q=' + encodeURIComponent(q);
// 'https://example.com/search?q=name%3DJohn%26age%3D30'encodeURI for a whole URL
encodeURI leaves : / ? # [ ] @ ! $ & ' ( ) * + , ; = alone so a complete URL stays structured. It still encodes spaces and non-ASCII. encodeURI('https://example.com/a b?x=1') is https://example.com/a%20b?x=1. encodeURIComponent of that same string wrecks the scheme: https%3A%2F%2Fexample.com%2Fa%20b%3Fx%3D1.
Use encodeURI only when the URL is already correctly split into syntax and data. It will not save you from an & inside a value — that & is reserved, so encodeURI keeps it and the query splits.
URLSearchParams and + versus %20
application/x-www-form-urlencoded historically encodes space as +. URLSearchParams follows that: new URLSearchParams({ q: 'hello world' }).toString() is q=hello+world. encodeURIComponent('hello world') is hello%20world. Both decode back to a space in the right decoder.
decodeURIComponent('hello+world') does **not** turn + into a space; it leaves the plus. params.get('q') on a URLSearchParams built from q=hello+world does. Pick one convention per layer. When you mix them, you get literal plus signs in search boxes.
new URLSearchParams({ q: 'hello world' }).toString();
// 'q=hello+world'
decodeURIComponent('hello%20world');
// 'hello world'
decodeURIComponent('hello+world');
// 'hello+world'Unicode is UTF-8 percent bytes
Non-ASCII is not one %HH per character. The encoder UTF-8-encodes, then percent-encodes each byte. encodeURIComponent('नमस्ते') is %E0%A4%A8%E0%A4%AE%E0%A4%B8%E0%A5%8D%E0%A4%A4%E0%A5%87. That is six UTF-8 bytes for five Devanagari code points plus a virama.
Round-trip with decodeURIComponent. If you see %uXXXX, that is a non-standard escape() leftover — do not emit it. /tools/url-encoder uses the standard pair.
Decode once
If a value is already %20, encoding it again becomes %2520. Decode until you have the logical string, then encode once for the hop you are on. APIs that “helpfully” encode on both client and gateway produce %2526 for an ampersand.
decodeURI mirrors encodeURI: it will not decode %26 into &, because & is reserved. Use decodeURIComponent for values. Malformed % sequences throw URIError — catch it. Paste the raw query into /tools/query-params-to-json to see the object the URL actually carries.
Common pitfalls
Running encodeURI on a concatenation that already includes user values. Running encodeURIComponent on a full URL. Treating + as a space in decodeURIComponent. Double-encoding. Using escape / unescape.
Base64 in a query still needs percent-encoding unless you used the URL-safe alphabet. /tools/base64 URL-safe mode turns +/ into -_; you may still encode = if it is present.
encodeURIComponentper value;encodeURIonly for a trusted full URL.URLSearchParamsuses+for space;encodeURIComponentuses%20.नमस्ते→%E0%A4%A8%E0%A4%AE%E0%A4%B8%E0%A5%8D%E0%A4%A4%E0%A5%87.
Worked examples
Space in either function
hello worldhello%20worldBoth encodeURI and encodeURIComponent produce this. Switch modes on /tools/url-encoder.
A value that looks like a query
encodeURIComponent('name=John&age=30')name%3DJohn%26age%3D30encodeURI would leave = and & in place and split the query if you append it raw.
Devanagari as UTF-8 bytes
encodeURIComponent('नमस्ते')%E0%A4%A8%E0%A4%AE%E0%A4%B8%E0%A5%8D%E0%A4%A4%E0%A5%87Each %HH is one UTF-8 byte, not one character.
Frequently asked questions
When do I use encodeURI instead of encodeURIComponent?
Only when you already have a structurally valid URL and need to escape stray spaces or Unicode in it. Query values always want encodeURIComponent.
Why is my space a plus?
URLSearchParams and form bodies use +. encodeURIComponent uses %20. decodeURIComponent will not treat + as a space.
Why did %20 become %2520?
The value was encoded twice. Decode to the logical string, then encode once for the URL you are building.
Does encodeURI encode ampersands?
No. & is reserved, so encodeURI keeps it. That is why it is the wrong function for a query value that contains &.
Is encoding done on a server here?
No. /tools/url-encoder runs encodeURI / encodeURIComponent in the browser. /tools/query-params-to-json parses the query in the same tab.
Summary
Encode each query value with encodeURIComponent, reserve encodeURI for complete URLs, and remember URLSearchParams speaks + while encodeURIComponent speaks %20. Confirm name=John&age=30 → name%3DJohn%26age%3D30 and नमस्ते → %E0%A4%A8%E0%A4%AE%E0%A4%B8%E0%A5%8D%E0%A4%A4%E0%A5%87 on /tools/url-encoder, then parse the finished query with /tools/query-params-to-json.