URL Encoding Decoded: A Developer's Guide to encodeURI vs encodeURIComponent

Originally published on — supports both encodeURIComponent and encodeURI modes with instant bidirectional conversion. All processing happens in your browser — zero data leaves your machine.

What is URL Encoding?

URL encoding (also called percent-encoding) converts special characters into a format that can be safely transmitted in URLs. Only a limited set of characters are allowed unescaped in URLs: alphanumeric characters (A-Z, a-z, 0-9) and a few special characters like -, _, ., ~.

Everything else gets encoded as a % followed by two hexadecimal digits representing the character's UTF-8 byte value.

The Two JavaScript Encoding Functions

JavaScript provides two built-in URL encoding functions — and choosing the wrong one is one of the most common bugs in web development.

encodeURI() — For Full URLs

encodeURI("https://example.com/search?q=hello world&lang=en")

// Result: "https://example.com/search?q=hello%20world&lang=en"

encodeURI() encodes special characters except those that have structural meaning in a URL (?, &, =, #, /). It assumes you're encoding a complete URL and preserves its structure.

Use when: you have a complete URL that contains characters needing encoding (like spaces in the path).

encodeURIComponent() — For Query Parameters

encodeURIComponent("hello world & more")

// Result: "hello%20world%20%26%20more"



encodeURIComponent("name=John & age=30")

// Result: "name%3DJohn%20%26%20age%3D30"

encodeURIComponent() encodes everything — including ?, &, =, #, and /. This is what you want when building query strings.

Use when: building query parameters, encoding user input for URLs, or handling data that needs to be embedded in a URL.

🔴 The Classic Bug

// ❌ WRONG — using encodeURI for query params

const name = "John & Jane";

const url = `https://api.example.com?name=${encodeURI(name)}`;

// Result: "https://api.example.com?name=John%20&%20Jane"

//                            The "&" was NOT encoded! ← BROKEN QUERY



// ✅ CORRECT — using encodeURIComponent for query params

const url = `https://api.example.com?name=${encodeURIComponent(name)}`;

// Result: "https://api.example.com?name=John%20%26%20Jane"

//                            Everything is encoded ✓

The Golden Rule: When building URL query strings, always use encodeURIComponent() for each parameter value. Never pass raw user input into a URL.

The Complete Character Reference

Here's what the two encoding modes leave untouched:

Real-World Scenarios

1. Building a Search URL

const baseUrl = "https://api.books.com/search";

const query = "JavaScript & CSS";

const category = "web dev";

const page = 1;



// ✅ Correct approach

const params = new URLSearchParams({

  q: query,

  cat: category,

  page: page.toString()

});



const url = `${baseUrl}?${params.toString()}`;

// "https://api.books.com/search?q=JavaScript+%26+CSS&cat=web+dev&page=1"

Pro tip: Use URLSearchParams instead of manual string concatenation — it handles encoding correctly for all browsers.

2. Decoding URLs from Server Logs

Raw log entry:

  GET /search?q=JavaScript+%26+CSS&referrer=https%3A%2F%2Fgoogle.com



After decoding:

  Path: /search

  q: JavaScript & CSS

  referrer: https://google.com

3. Handling Unicode and Emoji

encodeURIComponent("你好世界")

// Result: "%E4%BD%A0%E5%A5%BD%E4%B8%96%E7%95%8C"



encodeURIComponent("🔥 🚀")

// Result: "%F0%9F%94%A5%20%F0%9F%9A%80"



// ✅ Decoding is symmetrical

decodeURIComponent("%E4%BD%A0%E5%A5%BD")

// Result: "你好"

4. OAuth Redirect URLs

OAuth flows often require encoding the redirect_uri parameter:

const redirectUri = "https://myapp.com/callback?source=email&plan=premium";

const encoded = encodeURIComponent(redirectUri);

// "https%3A%2F%2Fmyapp.com%2Fcallback%3Fsource%3Demail%26plan%3Dpremium"



const oauthUrl = `https://auth.provider.com/authorize?redirect_uri=${encoded}&client_id=abc123`;

Common Pitfalls

Pitfall 1: Double Encoding

const input = "hello%20world";



// 🔴 Double encoding — the %25 will be treated as a literal percent

const bad = encodeURIComponent(input);

// Result: "hello%2520world"

//                 ^^ This is "%25" followed by "20", NOT a space!



// ✅ Correct — only encode once

const good = input; // Already encoded, or use decodeURIComponent first

Pitfall 2: Forgetting to Decode on the Backend

Most web frameworks handle URL decoding automatically (Express, Flask, Spring Boot all do). But if you're building a custom URL parser, remember to call decodeURIComponent().

Pitfall 3: The + vs %20 Confusion

Application/x-www-form-urlencoded forms encode spaces as +. But URL encoding (percent-encoding) uses %20. JavaScript's encodeURIComponent() uses %20, not +. URLSearchParams uses +. Both work — just be consistent.

Language Quick Reference

URL Encoding Cheat Sheet

Quick Decision Tree

You have a complete URL?       → use encodeURI()

You have a query param value?  → use encodeURIComponent()

You're debugging encoded data? → use decodeURIComponent()

Building query strings?        → use URLSearchParams() ✓

Characters That Must Always Be Encoded in Query Params

<space>  →  %20    # hash    →  %23

&        →  %26    % percent → %25

?        →  %3F    / slash  →  %2F

=        →  %3D    @ at     →  %40

TL;DR — Just Remember This

1. 
   encodeURIComponent() for query parameter values (encodes everything)


2. 
   encodeURI() only if you need to encode a complete URL string


3. 
   Use URLSearchParams — it handles both encoding and parameter formatting


4. 
   All encoding/decoding is local — no server processing required

🛠 Need a quick encode/decode? Try the and JWT Decoder for more handy dev tools.

Found this helpful? Follow me for more developer guides and practical web development tips. If you spot an error or have a suggestion, drop a comment below!