Ever clicked a link with %20 or %3D in it and wondered what those strange codes mean? That's URL encoding in action. It's how the web handles spaces, special characters, and non-ASCII text in URLs. Get it wrong, and your links break, forms fail, or APIs return errors. This guide explains exactly when and how to encode URLs properly.
Key Takeaways
- 1URL encoding converts unsafe characters to %XX format (hex ASCII/UTF-8 values)
- 2Use encodeURIComponent for query values and path segments; encodeURI for full URLs (rarely needed)
- 3Never double-encode: encode raw values once, at the final step before sending
- 4Space can be + (forms only) or %20 (works everywhere)—use %20 when in doubt
- 5Modern approach: Use URL and URLSearchParams APIs for automatic, correct encoding
1What Is URL Encoding?
URL encoding (also called percent-encoding) converts characters that aren't allowed in URLs into a safe format. Each unsafe character becomes a percent sign followed by two hexadecimal digits representing its ASCII/UTF-8 value.
Example: Basic Encoding
Scenario
Encode a search query with spaces and special characters
Solution
"Hello World!" → "Hello%20World%21" — Space becomes %20 (hex 20 = decimal 32, the ASCII code for space). Exclamation mark becomes %21.
| Character | Encoded | Reason |
|---|---|---|
| Space | %20 or + | Not allowed in URLs |
| & | %26 | Query string separator |
| = | %3D | Key-value separator |
| ? | %3F | Query string start |
| # | %23 | Fragment identifier |
| / | %2F | Path separator |
| + | %2B | Often means space in forms |
2When to Encode (and When Not To)
The tricky part of URL encoding is knowing when to apply it. Encoding the wrong parts of a URL breaks it just as badly as not encoding the right parts.
| URL Part | Encode? | Example |
|---|---|---|
| Protocol (https://) | Never | https:// stays as-is |
| Domain (example.com) | Never | Use Punycode for internationalized domains |
| Path segments | Encode values | /users/John%20Doe |
| Query parameter names | Encode | my%20key=value |
| Query parameter values | Always encode | search=hello%20world |
| Fragment (#section) | Encode value | #section%20name |
Never double-encode! If a value is already encoded (%20), encoding it again produces %2520 (the percent sign gets encoded). Always work with raw values and encode once at the end.
URL Encoding in JavaScript
JavaScript provides multiple encoding functions. Using the wrong one is a common source of bugs.
| Function | Use For | Does NOT Encode |
|---|---|---|
| encodeURIComponent() | Query params, path segments | A-Z a-z 0-9 - _ . ! ~ * ' ( ) |
| encodeURI() | Full URLs (rarely needed) | All above + : / ? # [ ] @ ! $ & ' ( ) * + , ; = |
| escape() ❌ | DEPRECATED - never use | Inconsistent, doesn't handle UTF-8 |
Example: Building a URL Correctly
Scenario
Create a search URL with user input that might contain special characters
Solution
const url = `https://api.example.com/search?q=${encodeURIComponent(userInput)}&page=1`; — Only encode the value, not the whole URL. The ? and & must stay unencoded.
Modern JavaScript: Use the URL and URLSearchParams APIs. They handle encoding automatically: new URL("https://example.com"); url.searchParams.set("q", "hello world");
4Common URL Encoding Mistakes
These bugs appear constantly in production code. Learn to recognize and avoid them.
| Mistake | Problem | Fix |
|---|---|---|
| Double encoding | %20 becomes %2520 | Encode once, at the end |
| Encoding whole URL | https%3A%2F%2F breaks URL | Only encode values, not structure |
| Not encoding at all | Spaces break URL, & splits values | Always encode user input |
| Using encodeURI for params | Doesn't encode &, =, ? | Use encodeURIComponent |
| Forgetting + vs %20 | Plus decoded as space in forms | Use %20 in path, + or %20 in query |
| Mixing encoded/decoded | Inconsistent handling | Decode on receive, encode on send |
Example: The Double-Encoding Bug
Scenario
User searches for "50% off" — you encode it, store it, then encode again when building the URL
Solution
First encode: "50%25%20off" (correct). Second encode: "50%2525%2520off" (broken). Solution: Track whether data is encoded or raw. Encode only once.
Special Cases & Edge Cases
Some encoding scenarios require special handling beyond basic encodeURIComponent.
- **Unicode/Emoji** – Encoded as UTF-8 bytes: 🎉 → %F0%9F%8E%89
- **Plus sign (+)** – Encode as %2B if you want a literal plus, not a space
- **Slash in path** – Use %2F only if slash is data, not a path separator
- **Reserved characters in values** – Always encode: & = ? # when they're data
- **Form data (application/x-www-form-urlencoded)** – Space as +, not %20
- **RFC 3986 strict** – Also encode ! ' ( ) * for maximum compatibility
The + vs %20 difference matters! In query strings, + traditionally means space (from HTML forms). In paths, + is a literal plus. When in doubt, use %20 — it works everywhere.
6URL Encoding for APIs
API calls frequently involve URL encoding. Here's how to handle common scenarios correctly.
| Scenario | Approach |
|---|---|
| Query parameters | Always encodeURIComponent values |
| Path parameters | Encode each segment separately |
| JSON in URL | JSON.stringify then encodeURIComponent |
| Arrays in query | ids=1&ids=2 or ids=1,2 or ids=[1,2] (API-specific) |
| OAuth tokens | Encode before including in URL |
| Webhook URLs | Full URL as parameter: callback=https%3A%2F%2F... |
Example: Passing a URL as a Parameter
Scenario
Call an API with a callback URL: https://api.com/share?url=https://mysite.com/page?id=123
Solution
Encode the callback: /share?url=https%3A%2F%2Fmysite.com%2Fpage%3Fid%3D123 — The inner ? and = must be encoded so they're not parsed as part of the outer query string.
7Decoding URLs
Decoding reverses the encoding process. Use the right function and handle errors gracefully.
| Function | Use For | Notes |
|---|---|---|
| decodeURIComponent() | Query params, path segments | Throws on malformed input |
| decodeURI() | Full URLs (rare) | Doesn't decode reserved chars |
| URLSearchParams.get() | Query params | Auto-decodes, handles + as space |
| unescape() ❌ | DEPRECATED | Never use |
decodeURIComponent throws URIError on invalid sequences like %ZZ or truncated %2. Always wrap in try-catch when processing untrusted input.
Encode & Decode URLs Online
Use our free URL Encoder tool to quickly encode or decode URLs, query strings, and special characters—all processed locally in your browser.
Open URL EncoderURL Encoding in Other Languages
Every programming language has URL encoding functions. Here's a quick reference.
| Language | Encode | Decode |
|---|---|---|
| Python | urllib.parse.quote(s, safe="") | urllib.parse.unquote(s) |
| PHP | rawurlencode($s) | rawurldecode($s) |
| Java | URLEncoder.encode(s, "UTF-8") | URLDecoder.decode(s, "UTF-8") |
| C# | Uri.EscapeDataString(s) | Uri.UnescapeDataString(s) |
| Ruby | CGI.escape(s) | CGI.unescape(s) |
| Go | url.QueryEscape(s) | url.QueryUnescape(s) |
PHP has urlencode (spaces as +) and rawurlencode (spaces as %20). Use rawurlencode for path segments, urlencode for form data.
Frequently Asked Questions
What's the difference between %20 and + for spaces?
Both represent spaces, but in different contexts. %20 works everywhere and is the standard RFC 3986 encoding. + is only valid in query strings (application/x-www-form-urlencoded, from HTML forms). In URL paths, + is a literal plus sign. When in doubt, use %20.
Why do I see %2F instead of / in some URLs?
The forward slash is a path separator in URLs. If you need a literal slash as data (like in a filename), it must be encoded as %2F. Otherwise the server interprets it as a directory separator. Example: /files/path%2Fto%2Ffile.txt passes "path/to/file.txt" as a single segment.
Should I encode URLs for SEO?
Search engines handle encoded URLs fine, but human-readable URLs are better for usability. Use hyphens instead of spaces (/my-page not /my%20page). Most web frameworks do this automatically. Only encode special characters that would break the URL.
How do I encode a full URL that includes query parameters?
Don't encode the whole URL at once. Parse it into parts, encode only the values, then reassemble. In JavaScript: use the URL API with url.searchParams.set() which handles encoding automatically. Or encode values individually with encodeURIComponent before concatenating.
What characters are "safe" and don't need encoding?
Unreserved characters (RFC 3986) are safe anywhere: A-Z, a-z, 0-9, hyphen (-), underscore (_), period (.), tilde (~). Reserved characters like ? & = / # have special meaning and must be encoded when used as data. Encode everything else to be safe.