← Guides

Developer Guide

URL Encoding for Query Strings

Percent-encode query values with encodeURIComponent, not the whole URL. Covers &, =, +, spaces, UTF-8 bytes, and how to parse the result back to JSON.

url encode query stringencodeuricomponentpercent encoding queryplus versus %20utf-8 query parameters

A search box that accepts C++ and name=John&age=30 will wreck a hand-built URL. & starts the next pair, = splits keys from values, and a raw space is simply illegal in the query. Percent-encoding exists so those characters can travel as data instead of syntax.

The rule that saves hours is: encode each value (and, if it is not a token you control, each key) with encodeURIComponent. Do not run encodeURI on the entire address and hope the reserved characters inside values survive. /tools/url-encoder exposes both functions so you can see the difference on one string.

Reserved characters: &, =, +, and space

In a query string, & delimits pairs and = delimits the key from the value. If a value contains either character, it must become %26 or %3D. A space becomes %20 in RFC 3986. In application/x-www-form-urlencoded (HTML forms), a space may also become +.

+ in a value you care about (C++) is not a space. If you decode with a form decoder, C++ becomes C (C, space, space) unless you encoded the pluses as %2B first. Encode values before you join them with &.

encodeURIComponent per value, not encodeURI on the URL

encodeURIComponent encodes everything except A–Z a–z 0–9 - _ . ~ (and a few extras in older engines). That is what you want for a query value. encodeURI leaves : / ? # [ ] @ ! $ & ' ( ) * + , ; = alone so a full URL stays structured — which means it will not encode the & inside a parameter.

On /tools/url-encoder, switch modes explicitly. hello world → hello%20world with encodeURIComponent. name=John&age=30 → name%3DJohn%26age%3D30. That second result is a single value, not a query string with two pairs.

+ versus %20

Browsers submitting GET forms use + for spaces. URLSearchParams and /tools/query-params-to-json decode both + and %20 as spaces, matching that form encoding. If you are building a query by hand for an API that treats + as a plus sign, use %20 for spaces and %2B for plus.

When in doubt, look at what the server’s framework decodes. Do not mix a %20 API with a client that sends + without checking.

Double-encoding

Encoding an already-encoded value turns %20 into %2520. The server decodes once and still sees %20 as literal text, so the search looks for a percent sequence instead of a space. Decode before you re-encode, or better, keep values in raw form until the last join.

Copy a suspicious URL into /tools/query-params-to-json to see the decoded object. If a value still contains %, it was probably encoded twice.

UTF-8 percent bytes

Non-ASCII is encoded as UTF-8 bytes, then each byte as %HH. नमस्ते becomes %E0%A4%A8%E0%A4%AE%E0%A4%B8%E0%A5%8D%E0%A4%A4%E0%A5%87 on /tools/url-encoder. Latin-1 shortcuts from the 1990s will corrupt that string.

Path segments need the same discipline as query values if they carry user text. The ? and # that start query and fragment still must not be encoded when they are syntax; they must be encoded when they are data.

Common pitfalls

Building ?q= + userInput with no encoding is an open redirect to “whatever the user typed, including extra parameters.” Using encodeURI on that concatenation leaves & intact. Using encodeURIComponent on the full https://example.com/search?q=… destroys the : and /.

Another trap: decoding with decodeURI and wondering why %26 is still there — that function also spares reserved characters. Use decodeURIComponent for values. Round-trip through /tools/url-encoder and /tools/query-params-to-json before you blame the backend.

  • Encode values, then join with & and =.
  • C++ needs %2B%2B if + means space on the server.
  • encodeURI is for a whole URL you already trust.

Worked examples

Worked search URL

Input
q = hello world · lang = C++ · sort = name=asc
Output
https://example.com/search?q=hello%20world&lang=C%2B%2B&sort=name%3Dasc

Each value ran through encodeURIComponent. The keys and the ? & = structure were left as syntax. Parse it back on /tools/query-params-to-json.

encodeURIComponent on a pair-shaped string

Input
name=John&age=30
Output
name%3DJohn%26age%3D30

This is one value. If you needed two parameters, encode John and 30 separately and write name=John&age=30 with only the values encoded.

Frequently asked questions

Should I encode the entire URL?

No. Use encodeURI only when the URL is already correctly structured and you need to escape stray Unicode or spaces in the whole thing. Query values need encodeURIComponent.

Why did my plus signs disappear?

A form decoder treats + as space. Encode plus as %2B. Check the decoded object on /tools/query-params-to-json.

How do I debug a live address-bar URL?

Paste it into /tools/query-params-to-json for a JSON view. Use /tools/url-encoder in decode mode on a single value that still looks wrong.

Is encoding done on a server here?

No. Both tools run in the browser. There is no URL-encoding API on thedevtools.in.

Summary

Treat &, =, +, and space as syntax until you encode them inside a value. Reach for encodeURIComponent on /tools/url-encoder, join the pairs yourself, and paste the finished URL into /tools/query-params-to-json to confirm the object you think you sent.

Try it yourself

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

Open Tool →