URL Encoder/Decoder

What is Percent-Encoding?

Percent-encoding (commonly called URL encoding) is a mechanism defined in RFC 3986 for encoding characters that are not allowed or have special meaning in a URI (Uniform Resource Identifier). Each unsafe character is replaced with a percent sign (%) followed by its two-digit hexadecimal ASCII code.

For example, a space character (ASCII 32, hex 20) becomes %20. The at sign @ (ASCII 64, hex 40) becomes %40. This ensures that every character in a URL is either a safe ASCII character or an explicit percent-encoded sequence with no ambiguity.

URLs can only contain a limited subset of ASCII characters. When a URL needs to include characters outside this set — spaces, non-ASCII characters, or characters that have reserved meaning in the URL syntax — percent-encoding is required. Without it, the URL would be malformed, ambiguous, or could be interpreted incorrectly by browsers and servers.

Reserved vs Unreserved Characters

RFC 3986 divides ASCII characters into three categories for URL purposes:

Unreserved Characters (never need encoding)

These characters can appear anywhere in a URL without encoding:

Category	Characters
Uppercase letters	A B C ... Z
Lowercase letters	a b c ... z
Digits	0 1 2 ... 9
Special	- _ . ~

Reserved Characters (context-dependent)

Reserved characters have special structural meaning in URLs. They must be percent-encoded when used as data (e.g., inside a query parameter value) but must not be encoded when used as delimiters:

Character	Purpose in URL	Encoded Form
:	Scheme separator (https:)	%3A
/	Path separator	%2F
?	Query string start	%3F
#	Fragment start	%23
&	Query parameter separator	%26
=	Key-value separator	%3D
@	Authority separator	%40
+	Space (in form encoding only)	%2B

Unsafe Characters (always need encoding)

Characters like spaces, quotes, angle brackets, and all non-ASCII characters (including UTF-8 multibyte characters like accented letters, CJK characters, and emoji) must always be percent-encoded. Non-ASCII characters are first encoded to UTF-8 bytes, then each byte is percent-encoded.

For example, the character e with acute accent is UTF-8 bytes C3 A9, which becomes %C3%A9 in the URL.

encodeURI vs encodeURIComponent

JavaScript provides two built-in functions for percent-encoding, and choosing the wrong one is one of the most common sources of URL bugs.

encodeURI()

Encodes a complete URL. It leaves URL-structural characters intact (/ ? # : @ & = + $) and only encodes characters that are illegal in any part of a URL (spaces, non-ASCII, etc.).

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

Use encodeURI() when you have a full URL string and want to make it safe without breaking its structure.

encodeURIComponent()

Encodes a URL component (a single parameter value, a path segment). It encodes everything except A-Z a-z 0-9 - _ . ~ — including reserved characters like / ? & =.

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

Use encodeURIComponent() when you are building a URL piece by piece and need to encode a parameter value. This prevents the value from being misinterpreted as URL structure.

The Golden Rule

When constructing URLs from dynamic values, always encode the values, never the structure:

// Correct
const url = `https://api.example.com/search?q=${encodeURIComponent(userInput)}`;

// Wrong — may break if userInput contains & or =
const url = `https://api.example.com/search?q=${userInput}`;

// Wrong — encodeURI won't encode & in the value
const url = encodeURI(`https://api.example.com/search?q=${userInput}`);

Common Use Cases

• Query parameters: When passing user input as URL query parameters (search terms, filters, form data), each parameter value must be percent-encoded to avoid breaking the URL structure
• REST API calls: API endpoints that accept path parameters or query parameters with special characters require proper encoding. Forgetting to encode a slash in a filename, for example, would create an incorrect path
• Redirect URLs: OAuth flows and single-sign-on systems frequently pass callback URLs as query parameters. The entire callback URL must be encoded so its ?, &, and = characters are not interpreted as part of the outer URL
• Internationalized domain names (IDN): While domain names use Punycode (not percent-encoding), the path and query portions of URLs use percent-encoding for non-ASCII characters
• HTML link attributes: When embedding URLs in HTML href attributes, characters like & must be both percent-encoded (for URL correctness) and HTML-entity-encoded (for HTML correctness), e.g., & in the HTML source