URL Encode / Decode

Why URLs need encoding

A URL is not free-form text. Certain characters carry structural meaning: ? starts the query string, & separates parameters, = divides a parameter name from its value, # begins a fragment, and / separates path segments.

If a value contains one of those characters, the URL breaks. A search for cats & dogs placed directly into ?q=cats & dogs would be read as a parameter q with the value cats , followed by a second parameter named dogs. The intended meaning is lost.

Percent-encoding solves this by replacing such characters with % followed by their byte value in hexadecimal. The & becomes %26, which no longer separates parameters but still decodes back to an ampersand on the receiving end.

How percent-encoding works

Each character to be encoded is converted to its UTF-8 bytes, and each byte is written as % plus two hexadecimal digits.

• A space is byte 0x20, so it encodes to %20
• ? is 0x3F, so it becomes %3F
• ä is two UTF-8 bytes (0xC3 0xA4), so it becomes %C3%A4
• An emoji is four UTF-8 bytes and produces four percent groups

Characters that are always safe, the so-called unreserved set, are left alone: letters, digits, and -, ., _, ~.

encodeURI versus encodeURIComponent

JavaScript offers two encoding functions, and choosing the wrong one is a common bug.

encodeURIComponent encodes a single value going into a URL, such as one query parameter. It escapes the structural characters &, =, ?, /, and #, which is exactly what you want for a value that must not affect the URL's structure.

encodeURI encodes a complete URL and deliberately leaves those same characters intact, because they are needed for the URL to work.

This tool uses encodeURIComponent, since encoding individual parameter values is by far the more common need. Using encodeURI on a parameter value is the classic source of URLs that work in testing and break as soon as a value contains an ampersand.

The plus sign problem

Spaces have two different encodings depending on context, which causes persistent confusion.

In a query string submitted by an HTML form, spaces are traditionally encoded as +, following the application/x-www-form-urlencoded convention. Everywhere else in a URL, a space is %20.

The consequence: a literal plus sign in a value must be encoded as %2B, otherwise the receiver may decode it as a space. This regularly breaks email addresses containing a plus, such as user+tag@example.com, which becomes user tag@example.com if the plus is left unencoded.

This tool encodes spaces as %20, which is valid everywhere. When decoding, be aware that a + in form-encoded data may have been a space originally.

Examples

Common pitfalls

Double encoding

Encoding an already-encoded string turns %20 into %2520, because the % itself gets encoded to %25. The receiver then decodes once and gets %20 as literal text rather than a space. If you see %25 where you did not expect it, something has been encoded twice.

Encoding the whole URL

Running an entire URL through encodeURIComponent destroys it: https://example.com/page becomes https%3A%2F%2Fexample.com%2Fpage, which is no longer a usable URL. Encode individual values, not the URL around them.

Forgetting to encode at all

Values coming from user input must always be encoded. Beyond breaking URLs, unencoded input can enable injection attacks in some contexts. Build URLs with a proper API, such as JavaScript's URLSearchParams, which handles encoding automatically.

Frequently asked questions

What happens if the input is malformed while decoding?

A stray % not followed by two hexadecimal digits produces a clear error message rather than a silent failure or a browser exception.

Should I use encodeURI or encodeURIComponent?

Use encodeURIComponent for individual parameter values, which covers almost every practical case. Use encodeURI only when encoding a complete URL that already contains its structural characters.

Why is a space sometimes %20 and sometimes +?

+ comes from the older form-encoding convention used in query strings, while %20 is the general URL encoding. %20 is valid everywhere and is the safer choice.

How do I encode a literal plus sign?

As %2B. Otherwise it may be decoded as a space, which is a frequent cause of broken email addresses in URLs.

Which characters do not need encoding?

Letters, digits, and the four characters -, ., _, ~. Everything else is safer encoded.

Is percent-encoding the same as HTML encoding?

No. Percent-encoding is for URLs and uses %XX. HTML encoding is for markup and uses entities such as &. They serve different contexts and are not interchangeable.

Related tools

• Base64 encoder and decoder, for binary-safe transport encoding
• JSON formatter, for inspecting decoded API payloads
• All developer tools