URL encoding: percent-encode the right part

Separate a URL into components

A URL can contain a scheme, host, port, path, query and fragment. Characters such as colon, slash, question mark, ampersand, equals and hash act as separators in particular positions. Encoding an entire already-structured URL with a component encoder turns those separators into data and can make the address unusable.

Use component encoding for a single path segment, query key or query value before inserting it into a URL. When building an application, prefer the platform URL and URLSearchParams APIs because they keep structure separate from values. A manual converter is most useful for inspection, debugging and one-off transformations.

Understand percent-encoded bytes

Percent encoding represents bytes as a percent sign followed by two hexadecimal digits. Modern web APIs normally encode Unicode text as UTF-8 first, so one visible character can become several percent sequences. A space commonly becomes %20 in a URL component, while HTML form encoding often represents a space as plus; those conventions are related but not identical.

Decode only when you know the input is encoded data. Invalid sequences such as a lone percent sign should produce an error rather than partial text. Decoding twice is dangerous because the first pass may reveal separators or another encoded sequence that changes meaning on the second pass.

Follow the living URL Standard

The WHATWG URL Standard is maintained as a living specification covering parsing, domains, percent encoding and form URL encoding. Browser behaviour has converged around these algorithms, but servers and older libraries can still normalize paths or queries differently. Test the complete request at the boundary that consumes it.

Internationalized domain names require domain processing rather than ordinary component encoding. Likewise, a full redirect target should be parsed and allowed by policy before use. Percent encoding does not make an unsafe URL trustworthy and does not prevent script injection when decoded text is later inserted into HTML.

Debug without changing meaning

When a URL fails, preserve the original and inspect one component at a time. Check whether a value was encoded zero times, once or twice. Compare the address bar, network request and server logs because display layers may show a decoded form while sending encoded bytes.

For signed URLs, OAuth callbacks and payment links, changing encoding can invalidate a signature or redirect check. Use the producing service's exact rules. Do not repair a security-sensitive URL by trial and error in production; reproduce it with test values and verify canonicalization on both sides.

Worked example: put a search phrase in a query

To create a search link for “cricket bat + gloves”, keep the page address and parameter separator as structure, then encode only the value. The plus sign in the original phrase is data and must not be confused with form-style space encoding. Building the query with URLSearchParams is safer in application code because it applies the expected form serialization consistently.

When debugging, compare the intended decoded value, the generated URL and what the server receives. If you paste an already encoded value into a builder that encodes again, each percent sign can become %25. Reverse only the layer you control. Never decode a full path blindly before authorization checks, because encoded separators and traversal sequences can acquire a new structural meaning.

Quick checklist

• Identify the path, query or fragment being encoded.
• Encode values rather than a complete structured URL.
• Distinguish %20 from form-style plus spaces.
• Avoid decoding the same value twice.
• Use URL APIs in application code.
• Recheck signatures and redirects after any normalization.

Primary references

Standards and platform support change. Use these authoritative sources to check the current specification and migration guidance.

• WHATWG — URL Standard
• MDN — encodeURIComponent