Boneyard Tools

encodeURIComponent vs encodeURI: which to use

The two browser encoders escape different characters. Learn when to reach for each, and why decoding does not turn a plus sign back into a space.

Why URLs need encoding at all

A URL uses a small set of characters as punctuation: the slash separates path segments, the question mark starts the query, and the ampersand joins parameters. If your data happens to contain those same characters, a reader cannot tell where your value ends and the URL grammar begins. Percent-encoding solves this by replacing a character with a percent sign followed by the hex value of its bytes, so a raw ampersand inside a value becomes %26 and can no longer be confused for a separator. Spaces and non-ASCII characters are encoded for the same reason, since they are not valid in a bare URL.

encodeURIComponent (the Component tab)

encodeURIComponent is the aggressive one. It escapes every character except the unreserved set A to Z, a to z, 0 to 9 and the marks - _ . ! ~ * ' ( ). That means slashes, colons, question marks, ampersands and equals signs all get encoded. This is exactly what you want for a single value that is going into one slot of a URL, such as a search term or a redirect target passed as a query parameter. Encode each value separately, then assemble the URL around the encoded pieces.

encodeURI (the Full URL tab)

encodeURI assumes you are handing it a whole, already-structured address, so it deliberately leaves the grammar characters alone: ; / ? : @ & = + $ , # all pass through untouched. It only escapes things that are never legal in a URL, chiefly spaces and non-ASCII letters. Use it when a link is already correct and you just need to tidy stray spaces or accented characters without breaking the path and query. If you ran Component over a full URL instead, you would encode the slashes and the whole address would stop resolving.

Decoding and the plus-sign trap

Decoding with decodeURIComponent is symmetric: it walks the string, turns each %XX group back into a byte, and reassembles UTF-8 sequences into characters. The one surprise is the plus sign. In the old form-encoding scheme a plus meant a space, but that rule is not part of percent-encoding, so decodeURIComponent leaves a literal + exactly as it found it. If you are decoding a form body where plus really did mean space, swap the pluses for spaces before you decode, otherwise you will see stray plus signs in your text.

Frequently asked questions

Which one do I use for a query parameter value?

Component (encodeURIComponent). It escapes the ampersand and equals sign that would otherwise break the parameter list, keeping your value contained to its own slot.

Can I encode a whole URL with Component?

No. Component escapes the slashes, colon and question mark, which corrupts the structure. Use Full URL for a complete address and Component only for the individual values inside it.

Why is my decoded text full of plus signs?

The source almost certainly used form encoding where + stands for a space. Decode does not translate + to space, so replace the plus signs with spaces first, then decode the rest.