Web Developmentbeginner7 min read

URL Encoding (Percent Encoding) Explained

Understand why URL encoding exists, how percent encoding works, the difference between encodeURI and encodeURIComponent, and common pitfalls in query strings.

Why URLs Need Encoding

URLs are restricted to a defined set of characters specified in RFC 3986. Characters fall into three categories:

Unreserved — `A-Z a-z 0-9 - . _ ~` — safe anywhere in a URL
Reserved — `: / ? # [ ] @ ! $ & ' ( ) * + , ; =` — have special meaning in URL structure
Unsafe — spaces, `<`, `>`, `{`, `}`, `|`, `\`, `^`, `` ` `` — must always be encoded

Without encoding, a space in a query parameter breaks the URL, an `&` is interpreted as a parameter separator, and a `#` is treated as the start of a fragment.

How Percent Encoding Works

Percent encoding replaces each unsafe byte with `%` followed by its two-digit hexadecimal value:

Space → `%20`
`&` → `%26`
`=` → `%3D`
`+` → `%2B`

For non-ASCII characters, the character is first converted to its UTF-8 byte sequence, then each byte is percent-encoded:

`é` → UTF-8 bytes `0xC3 0xA9` → `%C3%A9`
`中` → UTF-8 bytes `0xE4 0xB8 0xAD` → `%E4%B8%AD`

This ensures URLs containing any language's characters can be represented safely.

# The URL:
https://example.com/search?q=café latte&lang=fr

# Correctly encoded:
https://example.com/search?q=caf%C3%A9%20latte&lang=fr

Full URL Encoding vs Component Encoding

JavaScript provides two functions for URL encoding:

`encodeURI(url)` — encodes a complete URL. It preserves reserved characters that have structural meaning (`://`, `/`, `?`, `&`, `=`, `#`) because they're needed for the URL to work. Use this when you have a full URL string.

`encodeURIComponent(value)` — encodes a single URL component (like a query parameter value). It encodes reserved characters too, including `&` and `=`. Use this for individual values being inserted into a URL.

// Encoding a full URL — preserves structure
encodeURI('https://example.com/path?q=hello world');
// → 'https://example.com/path?q=hello%20world'

// Encoding a query parameter value — encodes everything unsafe
const query = 'price < 100 & category=books';
const url = `https://example.com/search?q=${encodeURIComponent(query)}`;
// → 'https://example.com/search?q=price%20%3C%20100%20%26%20category%3Dbooks'

Query String Gotchas

The `+` for space — HTML forms encode spaces as `+` in `application/x-www-form-urlencoded` format, while REST APIs expect `%20`. Mixing these causes subtle bugs. `decodeURIComponent` handles `%20` but not `+`; use `URLSearchParams` which handles both.
Double-encoding — if you encode a value that's already encoded, you get `%2520` (encoding the `%` sign) instead of `%20`. Always encode raw values, not pre-encoded ones.
Special params — some characters that look safe in a URL (`[`, `]`, `'`) are technically invalid in query strings and must be encoded for maximum compatibility.

// Safe way to build query strings — handles all edge cases
const params = new URLSearchParams({
  q: 'café latte',
  page: '2',
  filter: 'price < 100'
});
const url = `https://api.example.com/search?${params}`;
// → 'https://api.example.com/search?q=caf%C3%A9+latte&page=2&filter=price+%3C+100'

URL Structure Deep Dive

A complete URL has several distinct components, each with its own encoding rules:

`https://user:pass@api.example.com:8080/v1/search?q=hello&page=2#results`

Scheme — `https` — only letters, digits, `+`, `-`, `.`
Authority — `user:pass@api.example.com:8080` — credentials (deprecated), host, optional port
Path — `/v1/search` — segments separated by `/`; each segment can contain unreserved chars plus `:@!$&'()*+,;=`
Query — `q=hello&page=2` — key=value pairs separated by `&`; values should use `encodeURIComponent`
Fragment — `results` — client-side only, never sent to the server

Encoding and Parsing URLs with DevForge

The DevForge URL Encode/Decode tool handles both full URL encoding and component encoding, letting you instantly transform values without writing JavaScript. Paste an encoded URL to decode it for readability, or encode raw text to embed in a URL safely.

The URL Parser tool splits any URL into its labeled components — scheme, host, port, path, query parameters, and fragment — making it easy to inspect API endpoints or debug URL-construction bugs.

Try it on DevForge

Free online tools related to this tutorial — no signup required.

URL Encode/Decode

Encode & decode URLs

URL

URL Parser

Parse URL components

B64

Base64 Encode/Decode

Encode & decode Base64