🔗 URL Encoding Explained: The Complete Guide Based on RFC 3986

You build a URL with query parameters: https://api.example.com/search?q=coffee & tea. It breaks. The space, the ampersand — they have special meanings in URLs. URL encoding (also called percent-encoding, defined in RFC 3986) is how you safely include any character in a URL. The rules are precise and non-negotiable. Here they are.

The Two Kinds of Encoding (Critical Distinction)

JavaScript has two encoding functions, and using the wrong one is one of the most common web development bugs. The difference matters:

• encodeURI() — Encode a full URL: Preserves URL structural characters that have special syntactic meaning: : / ? # [ ] @ ! $ & ' ( ) * + , ; =. Only encodes characters that are never allowed in any URL component. Use this when you have a complete URL and want to make it safe.
• encodeURIComponent() — Encode a parameter VALUE: Encodes everything except: A-Z a-z 0-9 - _ . ! ~ * ' ( ). This includes &, =, ?, #, / — all the characters that have structural meaning. Use this when you're encoding a single query parameter value or URL path segment.

The classic mistake: using encodeURIComponent() on a full URL, which encodes the :// and ? and &, turning your URL into mush. Using encodeURI() on a query parameter value that contains &, which doesn't encode it, so the & is treated as a parameter separator instead of literal text.

The Correct Pattern

// ✅ Correct: encodeURIComponent on each parameter VALUE
const searchTerm = "coffee & tea";
const url = "https://api.example.com/search?q="
          + encodeURIComponent(searchTerm);
// Result: https://api.example.com/search?q=coffee%20%26%20tea

// ❌ Wrong: encodeURI on the parameter value
// "coffee & tea" → "coffee%20&%20tea" (the & is NOT encoded!)

// ❌ Wrong: encodeURIComponent on the whole URL
// "https://api.example.com/search?q=coffee" →
// "https%3A%2F%2Fapi.example.com%2Fsearch%3Fq%3Dcoffee"

Build your URLs using the URL constructor when available (browsers, Node.js 10+):

const url = new URL("https://api.example.com/search");
url.searchParams.set("q", "coffee & tea");
url.searchParams.set("page", "1");
console.log(url.toString());
// https://api.example.com/search?q=coffee+%26+tea&page=1

URL.searchParams handles encoding automatically and correctly. This is the safest approach — no manual encoding decisions to get wrong.

Character Encoding Reference

Common Encoding Pitfalls

• Double-encoding: Encoding an already-encoded string. %20 becomes %2520 (the % in %20 was encoded to %25). Decode once first, then re-encode.
• Not decoding on the server: Some server frameworks auto-decode query parameters; others don't. Always check if you're getting coffee%20%26%20tea as a raw string or as coffee & tea.
• Encoding path segments: If your URL path contains a variable that might include / or other special chars, encode it with encodeURIComponent. Otherwise the / becomes a path separator.
• Reserved vs unreserved characters: Per RFC 3986, unreserved characters (A-Z a-z 0-9 - _ . ~) should NEVER be percent-encoded because they have no special meaning. Encoding them is harmless but unnecessarily bloats URLs.

Use the Free Online Encoder/Decoder

For quick encoding/decoding, paste your URL or text into the URL Encoder/Decoder. It correctly handles encodeURI vs encodeURIComponent, supports batch encoding, and can decode already-encoded URLs for debugging.