Complete Guide to URL Encoding: Percent-Encoding Principles and Practice

URL Structure Recap

https://user:pass@www.example.com:8080/path/to/page?name=张三&age=25#section
└──┬──┘ └────┬────┘ └──────┬──────┘└─┬─┘└────┬─────┘└──────┬──────┘└──┬──┘
  scheme   userinfo     host      port    path        query     fragment

Only the path, query, and fragment parts need encoding. Scheme and host follow their own rules.

Why URL Encoding Is Needed

URLs can only contain printable ASCII characters. The following must be encoded:

Character	Encoding	Reason
Space	`%20` or `+`	Bare spaces are not allowed
Chinese「张三」	`%E5%BC%A0%E4%B8%89`	Non-ASCII
`&`	`%26`	Query separator
`=`	`%3D`	key=value separator
`#`	`%23`	Fragment marker
`?`	`%3F`	Query start
`/`	`%2F`	Path separator

Using the ToolsKu URL Encode/Decode Tool

Steps

Open the URL Encode/Decode tool
Enter a URL or text
Choose encode or decode
View the result

encodeURI vs encodeURIComponent

Function	Not encoded	Use case
`encodeURI()`	`: / ? # [ ] @ ! $ & ' ( ) * + , ; =`	Full URL
`encodeURIComponent()`	`A-Z a-z 0-9 - _ . ! ~ * ' ( )`	URL parameter values

const base = 'https://example.com/search';

// ✅ Encode parameter values
const url = `${base}?q=${encodeURIComponent('hello world')}`;
// → https://example.com/search?q=hello%20world

// ❌ Encode the entire URL
const wrong = encodeURIComponent('https://example.com/search?q=test');
// → https%3A%2F%2Fexample.com%2Fsearch%3Fq%3Dtest

Practical Scenarios

Chinese query parameters

Original: https://search.com/q=前端开发
Encoded:  https://search.com/q=%E5%89%8D%E7%AB%AF%E5%BC%80%E5%8F%91

Parsing URL parameters

Use the URL Parse tool to break down a URL and display query parameters in a table:

Input: https://api.com/users?name=张三&role=admin&page=1
Output:
  name  = 张三
  role  = admin
  page  = 1

Internationalized domain names (IDN)

Punycode encoding for the Chinese domain「工具库.com」:

工具库.com → xn--6qq986b3xl.com

Use the Punycode tool to convert between forms.

Base64-encoded URL parameters

Sometimes you need to encode a JSON object as a URL parameter:

{"user":"admin","role":"editor"}
  → Base64 → eyJ1c2VyIjoiYWRtaW4iLCJyb2xlIjoiZWRpdG9yIn0=
  → URL encode → eyJ1c2VyIjoiYWRtaW4iLCJyb2xlIjoiZWRpdG9yIn0%3D

Common Mistakes

Double encoding

Original:     hello world
Once encoded: hello%20world  ✅
Twice encoded: hello%2520world  ❌ (decode once → hello%20world)

Encoding the entire URL

Use encodeURIComponent only on parameter values, not on the full URL.

Space: `+` or `%20`?

In query parameters: + and %20 are equivalent
In paths: only %20 is valid
Recommendation: use %20 consistently

Summary

URL encoding is a fundamental Web development skill. Understanding the difference between encodeURI and encodeURIComponent, UTF-8 encoding for Chinese parameters, and Punycode for internationalized domains saves hours of debugging. ToolsKu provides URL Encode/Decode, URL Parse, and Punycode tools.