Parse and Decode Percent-Encoded URLs

URL Percent-Encoding

Percent-encoding (also called URL encoding) replaces unsafe characters with a % followed by two hexadecimal digits representing the character's byte value. This ensures URLs only contain valid ASCII characters.

How It Works

Original:  https://example.com/search?q=hello world&lang=日本語
Encoded:   https://example.com/search?q=hello%20world&lang=%E6%97%A5%E6%9C%AC%E8%AA%9E

Reserved vs Unreserved Characters

Unreserved characters (never need encoding):

A-Z  a-z  0-9  -  _  .  ~

Reserved characters (have special meaning in URLs):

:  /  ?  #  [  ]  @  !  $  &  '  (  )  *  +  ,  ;  =

These should only be encoded when used as data values, not when serving their syntactic purpose.

JavaScript Encoding Functions

Function	Encodes	Does NOT encode
encodeURI()	Spaces, non-ASCII	: / ? # [ ] @ ! $ & ' ( ) * + , ; =
encodeURIComponent()	Everything except	A-Z a-z 0-9 - _ . ~ ! ' ( ) *

encodeURI("https://example.com/path?q=hello world")
// "https://example.com/path?q=hello%20world"

encodeURIComponent("hello world & goodbye")
// "hello%20world%20%26%20goodbye"

When to Use Which

• encodeURI() — When encoding a full URL (preserves URL structure)
• encodeURIComponent() — When encoding a single parameter value
• URLSearchParams — Automatically handles encoding for query parameters

Common Encoding Pitfalls

1. Double encoding — Encoding an already-encoded URL produces %2520 instead of %20
2. Plus vs %20 — In query strings, + means space. In paths, it means a literal plus.
3. UTF-8 multibyte — Non-ASCII characters produce multiple %XX sequences
4. Decoding mismatch — Using decodeURI() on a component-encoded string can fail

Decoding

decodeURI("https://example.com/path%20with%20spaces")
// "https://example.com/path with spaces"

decodeURIComponent("hello%20world%20%26%20goodbye")
// "hello world & goodbye"