URL Encoding: How Percent-Encoding Works and When to Use It

URLs can only contain a limited set of ASCII characters. Everything else — spaces, Unicode, special symbols — must be percent-encoded. Understanding encoding is essential for building APIs, query strings, and handling user input correctly.

What Is URL Encoding?

URL encoding (also called percent-encoding) replaces unsafe characters with a % followed by two hexadecimal digits:

encodeURI vs encodeURIComponent

JavaScript has two encoding functions, and using the wrong one is a common bug:

• encodeURI() — Encodes a full URL. Leaves reserved characters (:/?#[]@!$&'()*+,;=) untouched so the URL structure is preserved.
• encodeURIComponent() — Encodes a URL component (like a query parameter value). Encodes ALL special characters including &, =, ?.

Common Pitfalls

1. Double encoding — Encoding an already-encoded string. %20 becomes %2520.
2. Not encoding user input — Unencoded user input in URLs can break APIs and create XSS vulnerabilities.
3. Using + for spaces — In query strings, + is sometimes used for spaces (form encoding), but %20 is the correct URL encoding.
4. Forgetting to decode — Displaying encoded URLs to users without decoding first.

When You Need to Encode

• Building API query strings with user input
• Passing URLs as parameters in other URLs
• Sending data in application/x-www-form-urlencoded requests
• Creating mailto: links with subject and body

The Bottom Line

1. URL encoding replaces unsafe characters with %XX sequences
2. Use encodeURIComponent() for query parameter values
3. Use encodeURI() for full URLs
4. Never double-encode — decode first if you're unsure
5. Always encode user input before putting it in a URL

Disclaimer: This guide is for informational purposes only. Always follow RFC 3986 standards for URL encoding in production applications.