Every time you click a link, submit a form, or call an API, your browser silently transforms the URL into a format that can travel safely across the internet. Spaces become %20, ampersands become %26, and characters from non-Latin scripts turn into long sequences of percent signs and hex digits. This process — URL encoding — is one of those foundational web concepts that most developers use every day without fully understanding. When it goes wrong, you get broken links, garbled parameters, and maddening bugs that are difficult to reproduce.
This guide walks through everything you need to know about URL encoding: how it works at the specification level, the difference between JavaScript's encoding functions, the characters that must be encoded (and those that must not), and the real-world pitfalls that catch even experienced developers.
What Is URL Encoding?
URL encoding, also known as percent-encoding, is the mechanism defined by RFC 3986 for representing characters in a URI that are not allowed in their literal form. The concept is simple: any character that is not part of the "unreserved" set is replaced by a percent sign followed by two hexadecimal digits representing the character's byte value in UTF-8.
For example, a space character (UTF-8 byte 0x20) becomes %20. The Japanese character "日" (UTF-8 bytes 0xE6 0x97 0xA5) becomes %E6%97%A5. This ensures that every URL can be expressed using only the ASCII character set, which is critical because URLs must be transmitted through protocols and systems that may only support ASCII.
Reserved vs. Unreserved Characters
RFC 3986 divides the ASCII characters that can appear in a URI into two groups, and understanding this distinction is the key to getting URL encoding right:
Unreserved Characters (Never Encode These)
These characters can appear literally anywhere in a URL and never need to be encoded:
A-Z a-z 0-9 - _ . ~That is: all uppercase and lowercase Latin letters, digits, hyphens, underscores, periods, and tildes. These 66 characters are safe in every part of a URL.
Reserved Characters (Context-Dependent)
These characters have special meaning in URLs as delimiters between components:
: / ? # [ ] @ ! $ & ' ( ) * + , ; =Reserved characters should only be encoded when they appear in a context where their literal presence would be ambiguous. For instance, / separates path segments, so it should not be encoded when used as a path delimiter — but it must be encoded if it appears as part of a filename or query parameter value. The character & separates query parameters, so it must be encoded if the literal ampersand is part of a parameter value.
encodeURIComponent vs. encodeURI in JavaScript
JavaScript provides two built-in functions for URL encoding, and using the wrong one is the source of an enormous number of bugs. Understanding the difference is non-negotiable for any web developer:
encodeURIComponent()
This function encodes everything except unreserved characters. It is designed for encoding a single component of a URI — such as a query parameter value, a path segment, or a fragment identifier. It will encode characters like /, ?, &, =, and #.
encodeURIComponent("hello world")
// "hello%20world"
encodeURIComponent("price=100¤cy=USD")
// "price%3D100%26currency%3DUSD"
encodeURIComponent("https://example.com/path")
// "https%3A%2F%2Fexample.com%2Fpath"encodeURI()
This function is designed for encoding an entire URI. It encodes the same characters as encodeURIComponent() but leaves reserved characters intact, because they are needed as structural delimiters in a complete URL.
encodeURI("https://example.com/path?q=hello world&lang=en")
// "https://example.com/path?q=hello%20world&lang=en"
encodeURI("https://example.com/café")
// "https://example.com/caf%C3%A9"The critical rule: use encodeURIComponent() when encoding parameter values, and use encodeURI() only when you have a complete URL that just needs non-ASCII characters encoded. In practice, encodeURIComponent() is what you need 90% of the time.
Quick Comparison Table
Character encodeURIComponent encodeURI
--------- ------------------ ---------
(space) %20 %20
/ %2F /
? %3F ?
& %26 &
= %3D =
# %23 #
@ %40 @Building Query Strings Correctly
Query strings are the most common place where encoding mistakes happen. A query string starts with ? and contains key-value pairs separated by &. Both keys and values must be individually encoded, but the structural ?, &, and = characters must remain unencoded.
The modern and correct way to build query strings in JavaScript is with the URLSearchParams API, which handles encoding automatically:
const params = new URLSearchParams({
query: "red shoes",
price_max: "50",
category: "clothing & accessories"
});
console.log(params.toString());
// "query=red+shoes&price_max=50&category=clothing+%26+accessories"
const url = new URL("https://shop.example.com/search");
url.search = params.toString();
console.log(url.href);
// "https://shop.example.com/search?query=red+shoes&..."Note that
URLSearchParamsencodes spaces as+rather than%20. Both are valid in query strings per theapplication/x-www-form-urlencodedspecification, but%20is technically correct per RFC 3986. Most servers handle both transparently.
Other languages have equivalent utilities. In Python, use urllib.parse.urlencode(). In PHP, use http_build_query(). In Go, use url.Values. Always prefer these purpose-built functions over manual string concatenation.
Need to quickly encode or decode a URL? Try our free URL Encoder/Decoder tool — instant results with no installation.
Open URL Encoder →International URLs and IDN
URLs that contain characters outside the ASCII range — such as Chinese, Arabic, Cyrillic, or accented Latin characters — require special handling. There are two distinct areas where non-ASCII characters appear:
Domain Names (Internationalized Domain Names)
Domain names like münchen.de or 例え.jp use a system called Punycode (defined by RFC 3492) to convert Unicode domain names into an ASCII-compatible encoding. The domain münchen.de becomes xn--mnchen-3ya.de. This conversion is handled by the browser and DNS resolver — you do not typically need to do it manually, but understanding that it exists helps when debugging DNS issues with international domains.
Path and Query Components
Non-ASCII characters in the path and query string are encoded as their UTF-8 byte sequences with percent-encoding. Modern browsers display the decoded Unicode characters in the address bar for readability, but the actual HTTP request uses the encoded form. For example:
// What the user sees in the address bar:
https://example.com/articles/café-guide
// What is actually sent over HTTP:
https://example.com/articles/caf%C3%A9-guideCommon Pitfalls and How to Avoid Them
1. Double Encoding
This is the most frequent URL encoding bug. It happens when a string that is already encoded gets encoded again, turning %20 into %2520 (the % itself gets encoded to %25). If your URLs contain sequences like %25 where you do not expect them, you are almost certainly double-encoding somewhere in your pipeline.
// WRONG — double encoding
const value = encodeURIComponent("hello world");
// "hello%20world"
const url = encodeURI(`https://api.example.com/search?q=${value}`);
// "https://api.example.com/search?q=hello%2520world" ← broken!2. Forgetting to Encode the Plus Sign
In query strings, + is interpreted as a space. If you need a literal plus sign in a query parameter value (common in base64 strings and phone numbers like +1-555-0100), you must encode it as %2B. The function encodeURIComponent() handles this correctly, but manual string manipulation often does not.
3. Not Encoding Hash Fragments
The # character marks the start of a fragment identifier. If a query parameter value contains a # and it is not encoded, the browser will interpret everything after it as a fragment rather than part of the query. This silently truncates your URL without any error message.
4. Server-Side Decoding Mismatches
Different web servers and frameworks decode URLs at different stages of request processing. Some frameworks automatically decode path segments before routing, while others pass them through encoded. This can lead to routing failures when paths contain encoded characters. Always test your application with URLs that contain encoded characters in paths and query strings.
Encoding in Other Languages
Every major programming language provides URL encoding utilities, but their behavior varies:
# Python
from urllib.parse import quote, quote_plus, urlencode
quote("hello world") # "hello%20world"
quote_plus("hello world") # "hello+world"
urlencode({"q": "a&b"}) # "q=a%26b"
// Java
URLEncoder.encode("hello world", "UTF-8") // "hello+world"
// Note: Java's URLEncoder uses + for spaces (form encoding)
// PHP
urlencode("hello world") // "hello+world"
rawurlencode("hello world") // "hello%20world"
// Go
url.QueryEscape("hello world") // "hello+world"
url.PathEscape("hello world") // "hello%20world"Notice the inconsistency: some functions encode spaces as + (form encoding) while others use %20 (RFC 3986). When moving data between systems written in different languages, ensure you are using compatible encoding and decoding functions.
Conclusion
URL encoding is a deceptively simple topic that trips up developers at every experience level. The rules themselves are straightforward — unreserved characters pass through untouched, everything else gets percent-encoded as UTF-8 bytes — but the interaction between different encoding functions, server-side decoding behavior, and legacy conventions like + for spaces creates a minefield of subtle bugs.
The safest approach is to always use your language's purpose-built URL construction APIs (URLSearchParams, urllib.parse, url.Values) rather than manually concatenating strings. When you do need to debug encoding issues, a reliable URL encoder/decoder tool is invaluable for quickly testing how specific characters are transformed.