What URL encoding does
URLs can only contain a small set of ASCII characters. Everything else, including spaces, accents, emoji and characters with special meaning like & and ?, is converted to UTF-8 bytes and written as % plus two hex digits. That’s called percent-encoding.
space → %20 & → %26 é → %C3%A9
/ → %2F ? → %3F 👋 → %F0%9F%91%8BWhich mode do I need?
| You’re encoding | Use | JavaScript |
|---|---|---|
| A query value, path segment or form field | Query value | encodeURIComponent() |
| A full URL that already has its structure | Whole URL | encodeURI() |
The safest pattern is to build URLs with the URL API and let it handle encoding:
const url = new URL('https://api.example.com/search');
url.searchParams.set('q', 'café & crème');
url.toString(); // https://api.example.com/search?q=caf%C3%A9+%26+cr%C3%A8meWhen decoding goes wrong
The browser’s decodeURIComponent gives up on the whole string at the first bad escape. This decoder keeps going, marks each problem in the input, and explains it:
- A broken escape like
50%off: a%must be followed by two hex digits. The fix writes it as%25. - Latin-1 escapes like
caf%E9come from older systems. They aren’t valid UTF-8, so they’re read as Windows-1252 (é) and can be converted to UTF-8 (%C3%A9). - Double encoding like
%2520: one click decodes the outer layer. - Plus signs in a query string usually mean spaces. You get a nudge to switch on “Treat + as space”.
- Encoding twice: in Encode mode, text that already contains escapes is flagged before you double-encode it.
The URL breakdown also flags query parameters that appear more than once, and values that are still encoded after decoding.
In other languages
# Python
from urllib.parse import quote, unquote, urlencode
quote('a b&c', safe='') # 'a%20b%26c'
urlencode({'q': 'a b'}) # 'q=a+b'
// Go
url.QueryEscape("a b&c") // "a+b%26c"
url.PathEscape("a b") // "a%20b"Need to put binary data in a URL? Use URL-safe Base64.
Questions people ask
What’s the difference between encodeURI and encodeURIComponent?
encodeURI is for a whole URL. It leaves : / ? # & = alone so the URL still works. encodeURIComponent is for one piece, such as a query value, and escapes those too. Using the wrong one is the most common URL bug.Should spaces be %20 or +?
+. In the path part of a URL only %20 works. When in doubt, use %20.Why is my text double-encoded?
%2520, something encoded an already-encoded string: %20 became %25 + 20. This tool spots it and decodes the second layer in one click. Then fix the code so it encodes only once.What does “URIError: malformed URI” mean?
% that isn’t followed by two hex digits, or the escapes don’t form valid UTF-8. A literal percent sign must be written %25. Paste the URL here and the broken escape is marked, while everything else still decodes.