URL Encoding Guide — Why Special Characters Break URLs

You paste a URL into a browser and it works. You put a space or ampersand in it and it breaks. URL encoding is the reason — and misunderstanding it causes subtle, hard-to-debug issues.

What Is Percent-Encoding?

URLs can only contain a limited set of ASCII characters. Any character outside that set must be represented as a percent sign followed by two hex digits. For example, a space becomes %20, and an ampersand becomes %26.

This is defined in RFC 3986. The characters that are safe to use unencoded in a URL are:

A-Z a-z 0-9 - _ . ~ (unreserved characters)

Reserved Characters

These characters have special meaning in URLs and must be encoded if used as data (not as delimiters):

• : — separates scheme from authority (https:)
• / — separates path segments
• ? — starts the query string
• & — separates query parameters
• = — separates parameter keys from values
• # — starts the fragment identifier
• + — treated as a space in query strings (a legacy convention from HTML forms)

encodeURI vs. encodeURIComponent

JavaScript provides two functions, and using the wrong one is the most common mistake:

encodeURI encodes a full URL. It leaves reserved characters like :, /, ?, &, and = intact because they’re structural.

encodeURIComponent encodes a single value. It encodes everything except unreserved characters, including &, =, and /.

// Encoding a full URL — use encodeURI
encodeURI("https://example.com/path?q=hello world")
// "https://example.com/path?q=hello%20world"

// Encoding a query parameter VALUE — use encodeURIComponent
const query = "price=10&currency=USD";
`https://example.com/search?q=${encodeURIComponent(query)}`
// "https://example.com/search?q=price%3D10%26currency%3DUSD"

If you use encodeURI on the query value above, the & and = would not be encoded, and the URL would be parsed as having extra parameters.

Common Mistakes

• Double encoding — encoding an already-encoded string turns %20 into %2520. Always encode raw values, never pre-encoded strings.
• Forgetting to encode — user input dropped straight into a URL can break parsing or create security vulnerabilities (open redirects, injection).
• Using + for spaces — the + = space convention only applies to application/x-www-form-urlencoded (HTML form submissions). In URL paths, + is a literal plus sign. Use %20 for spaces in paths.
• Encoding the whole URL with encodeURIComponent — this breaks the structure by encoding /, :, etc.

Query String Encoding in Practice

The modern approach in JavaScript is to use URLSearchParams, which handles encoding automatically:

const params = new URLSearchParams({
  q: "hello world",
  category: "food & drink",
});
params.toString();
// "q=hello+world&category=food+%26+drink"

// Or build a full URL
const url = new URL("https://example.com/search");
url.searchParams.set("q", "price > 100");
url.toString();
// "https://example.com/search?q=price+%3E+100"

Using URLSearchParams or the URL constructor is almost always better than manual string concatenation with encodeURIComponent. Let the platform handle the edge cases.

Related Tools

• URL Encoder/Decoder — encode and decode URLs with percent-encoding
• Base64 Encoder/Decoder — encode binary data as text for safe transmission