URL Encoding (Percent-Encoding) Explained: encodeURIComponent, Spaces, and Double Encoding

URLs can only contain a limited set of characters. To include anything else, such as spaces, accented letters, or symbols with special meaning, they are converted to percent-encoding: a percent sign followed by two hexadecimal digits representing the byte.

How it works

Text is first converted to bytes using UTF-8, and each byte that isn't allowed is written as %XX. A space is the byte 0x20, so it becomes %20. The letter e with an acute accent takes two bytes in UTF-8, so it becomes %C3%A9.

hello world      ->  hello%20world
a&b=c            ->  a%26b%3Dc
café             ->  caf%C3%A9

Reserved characters

• Characters like : / ? # [ ] @ ! $ & ' ( ) * + , ; = have special roles in URLs.
• If you want one of them as data (for example, an ampersand inside a query value), it must be encoded so it isn't mistaken for structure.
• Unreserved characters (letters, digits, - . _ ~) never need encoding.

encodeURI vs encodeURIComponent

• encodeURI() encodes a whole URL and leaves structural characters like : / ? & = # alone.
• encodeURIComponent() encodes a single value and does encode those characters, which is what you want for a query parameter or path segment.
• Use encodeURIComponent for values you insert into a URL; using encodeURI on a value would leave & and = unescaped and can corrupt the query string.

const q = "cats & dogs";
const url = "/search?q=" + encodeURIComponent(q);
// /search?q=cats%20%26%20dogs

%20 vs +

In a query string produced by an HTML form (application/x-www-form-urlencoded), spaces are written as +. In other parts of a URL, and in most modern APIs, a space is %20. Decoders for form data treat + as a space, so a literal plus sign must be sent as %2B.

Double encoding and other pitfalls

• Double encoding: encoding an already-encoded string turns %20 into %2520. Encode raw values exactly once.
• Decode once as well; decoding twice can change meaning and is a source of security bugs.
• Encode the value, not the whole URL with its structure.
• Let your HTTP client or URL builder handle it when possible instead of concatenating strings.