URL Encoding Explained: When to Use encodeURI vs encodeURIComponent
2026-07-29
URLs have a grammar. Slashes separate path segments, a question mark begins the query, ampersands separate parameters and a hash starts the fragment. Percent-encoding is how you put arbitrary text into a URL without those characters being read as structure.
Step by step
- Open the URL Encoder & Decoder.
- Choose encode or decode.
- Choose the scope — single value or whole URL. This is the important choice.
- Paste your text and copy the result.
The distinction that breaks links
There are two encoding functions and they are not interchangeable:
- Single value (
encodeURIComponent) escapes everything, including: / ? & = #. Use it for one query parameter or one path segment. - Whole URL (
encodeURI) leaves those structural characters alone. Use it to clean up a complete address.
Get it backwards and things break in two different ways. Encoding a complete URL as though it were a value turns https://example.com into https%3A%2F%2Fexample.com, which is no longer a link. Encoding a value as though it were a URL leaves an ampersand intact — so a search for "cats & dogs" silently becomes two query parameters, and your server sees a search for "cats".
A rule of thumb
If you are building a query string by joining pieces together, encode each piece with single-value scope. If you are fixing up something that is already a complete address, use whole-URL scope. When in doubt, ask whether the text you are encoding is part of the URL's structure or content inside it.
Decoding
Log files, redirect chains, analytics parameters and error messages are full of percent-escaped text that is unreadable at a glance. Decoding is often the fastest way to work out what a request was actually doing. If decoding fails, the text contains a lone % or an invalid pair like %ZZ — usually a sign it was truncated somewhere.