← Guides

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.

encodeURI vs encodeURIComponenturlsearchparams plus spacepercent encoding utf-8decodeURIComponentquery string javascript

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.

  • encodeURIComponent per value; encodeURI only for a trusted full URL.
  • URLSearchParams uses + for space; encodeURIComponent uses %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

Input
hello world
Output
hello%20world

Both encodeURI and encodeURIComponent produce this. Switch modes on /tools/url-encoder.

A value that looks like a query

Input
encodeURIComponent('name=John&age=30')
Output
name%3DJohn%26age%3D30

encodeURI would leave = and & in place and split the query if you append it raw.

Devanagari as UTF-8 bytes

Input
encodeURIComponent('नमस्ते')
Output
%E0%A4%A8%E0%A4%AE%E0%A4%B8%E0%A5%8D%E0%A4%A4%E0%A5%87

Each %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.

Try it yourself

Put what you've learned into practice with our free browser-native tool.

Open Tool →