What Does encodeURIComponent Do? A Simple Explanation with Examples

If you have built a URL in JavaScript, you have probably run into encodeURIComponent — and possibly its confusingly similar sibling, encodeURI. Using the wrong one is a classic bug that breaks links in subtle ways. Here is a clear explanation of what encodeURIComponent does, with examples, and a simple rule for choosing between the two.

What it does

encodeURIComponent takes a string and replaces any character that is not safe in a URL with its percent-encoded equivalent. A space becomes %20, an ampersand becomes %26, an equals sign becomes %3D, a question mark becomes %3F, and so on. The purpose is to make a piece of text safe to drop into a URL as a value — a search term, a parameter, a redirect target — without the special characters being misread as URL structure. It encodes everything that could cause a problem, which is exactly what you want for a single value.

A concrete example

Say you want to build a search URL for the query "cats & dogs". If you just concatenate it, you get ...?q=cats & dogs, which breaks — the ampersand is read as a parameter separator and the space is illegal. Run the value through encodeURIComponent first and "cats & dogs" becomes cats%20%26%20dogs, giving you ...?q=cats%20%26%20dogs, which the server correctly reads as the single value "cats & dogs". The encoding preserves your data's meaning by escaping the characters that would otherwise be structural.

encodeURIComponent vs encodeURI

The difference is what each one leaves alone. encodeURIComponent encodes everything reserved, including the URL structure characters like / ? & = # — because it assumes you are encoding a value that goes inside a URL. encodeURI deliberately does not encode those structure characters, because it assumes you are encoding a whole, already-built URL and want to keep it functional. So encodeURI('https://x.com?a=b c') keeps the ://, the ?, and the = intact and only fixes the space, while encodeURIComponent would escape all of them. Use component for the pieces, encodeURI for a whole URL.

The simple rule

Here is the rule that keeps you out of trouble: if you are encoding a value that goes inside a URL — a search term, a parameter value, a path segment, a redirect target — use encodeURIComponent. If you are encoding an entire URL that you want to remain a working URL, use encodeURI. When you are unsure, you almost always want encodeURIComponent, because you are almost always encoding a value, not a whole URL. Getting this right prevents the most common URL-building bugs.

Watch out for double-encoding

One trap: never run encodeURIComponent on a string that is already encoded. If you encode a value twice, the percent signs themselves get encoded — %20 becomes %2520 — and the link breaks. Only encode raw, un-encoded text. If you are not sure whether a string is already encoded, decode it first, then encode it exactly once. This double-encoding mistake is the source of the mysterious %2520 you sometimes see in broken URLs.