URL Encoding Demystified: Percent-Encoding in Practice

URLs can only safely carry a small set of ASCII characters, yet we routinely stuff names, emails, search terms, and JSON into them. Percent-encoding is the mechanism that bridges that gap, and getting it wrong produces some of the most persistent, hard-to-spot bugs in web development.

What percent-encoding actually is

A URL is defined by RFC 3986, and that spec only permits a limited alphabet of characters to appear directly in a URL. Anything outside that set, or any character that has a special structural meaning in the wrong place, must be escaped.

Percent-encoding works on bytes, not characters. The rule is simple:

1. Take the character and encode it as one or more bytes using UTF-8.
2. Replace each byte with a
   textCopy

   %
   followed by its two-digit uppercase hexadecimal value.

A space (byte

) becomes . An ampersand () becomes . A character outside ASCII, like , is two UTF-8 bytes () and therefore encodes to . An emoji is four bytes and becomes four percent-sequences.

textCopy
space  -> %20
&      -> %26
é      -> %C3%A9

This byte-level detail matters: percent-encoding is not "replace weird characters with codes," it is "serialize to UTF-8, then escape the bytes." Any encoder that doesn't go through UTF-8 first will mangle non-ASCII input.

Reserved vs unreserved characters

RFC 3986 splits characters into two groups that decide what needs escaping.

Unreserved characters

These are always safe and never need encoding:

textCopy
A-Z  a-z  0-9  -  _  .  ~

That's the entire unreserved set. Letters, digits, hyphen, underscore, period, and tilde. A correct encoder leaves these untouched. (Some older encoders escaped

because an obsolete spec listed it as reserved; modern ones should not.)

Reserved characters

Reserved characters have structural meaning in a URL. They are the delimiters that separate one part of the URL from another:

textCopy
:  /  ?  #  [  ]  @        (general delimiters)
!  $  &  '  (  )  *  +  ,  ;  =   (sub-delimiters)

The key insight is that reserved characters are only special in context. A

is meaningful when it separates path segments, but if a single path segment genuinely contains a slash as data, that slash must be encoded as so it isn't read as a separator. Same for introducing a query, introducing a fragment, and / separating query parameters.

This is why "do I need to encode this character?" has no universal answer. It depends entirely on where the character is going and whether it's acting as a delimiter or as literal data.

encodeURI vs encodeURIComponent

JavaScript ships two global functions, and the difference between them is the single most common source of URL bugs.

encodeURI: for a whole URL

assumes you are handing it a complete, already-structured URL and you just want to make it valid. It therefore leaves reserved delimiters alone, because escaping them would break the URL's structure.

jsCopy
encodeURI('https://example.com/search?q=a b&x=1');
// 'https://example.com/search?q=a%20b&x=1'

Notice that

, , , , and all survived. Only the space got encoded. That's correct for its job, but it means is the wrong tool for encoding a piece of a URL.

encodeURIComponent: for one piece

assumes you are encoding a single component that will be dropped into a larger URL, so it escapes everything that isn't unreserved, including reserved delimiters.

jsCopy
encodeURIComponent('a b&x=1');
// 'a%20b%26x%3D1'

Here

became and became , which is exactly what you want when those characters are data inside a value rather than structure.

The rule of thumb

• Building a URL from parts? Encode each part with
  textCopy

  encodeURIComponent
  , then assemble.
• Already have a full URL and just want to clean it up?
  textCopy

  encodeURI
  (rarely needed in practice).

Never use

to encode a query-parameter value. If a user's search term contains , will leave it intact and your query string will silently split into extra parameters.

Both functions deliberately leave a few characters unescaped that

arguably should escape: , , , , and . Most servers tolerate them, but if you need strict RFC 3986 compliance, post-process them yourself:

jsCopy
function strictEncode(str) {
  return encodeURIComponent(str).replace(
    /[!'()*]/g,
    c => '%' + c.charCodeAt(0).toString(16).toUpperCase()
  );
}

Encoding query parameters correctly

Query strings are where encoding goes wrong most often, because both the keys and the values can contain reserved characters.

The wrong way is to concatenate raw strings:

jsCopy
// BROKEN: breaks if name or note contains & = # or space
const url = `/save?name=${name}&note=${note}`;

If

is , the resulting URL has stray and characters that the server will parse as additional parameters.

Encode each key and value independently:

jsCopy
const url = `/save?name=${encodeURIComponent(name)}` +
            `&note=${encodeURIComponent(note)}`;

Better still, let

handle it. It encodes for you and removes the chance of forgetting one value:

jsCopy
const params = new URLSearchParams({
  name: name,
  note: 'cost = $5 & up',
});
const url = `/save?${params.toString()}`;
// /save?name=...&note=cost+%3D+%245+%26+up

The

API composes nicely with it:

jsCopy
const u = new URL('https://example.com/save');
u.searchParams.set('q', 'rock & roll');
u.toString(); // https://example.com/save?q=rock+%26+roll

Using these built-ins is almost always safer than hand-rolling string concatenation, and it sidesteps the next problem entirely.

The space and plus-sign trap

Here is the bug that surprises nearly everyone. There are two conventions for encoding a space in a URL, and they live in different parts of the URL.

• In the path, a space is
  textCopy

  %20
  . A
  textCopy

  +
  is a literal plus.
• In a query string using
  textCopy

  application/x-www-form-urlencoded
  (the format browsers use for form submissions), a space is
  textCopy

  +
  , and a literal plus is
  textCopy

  %2B
  .

This split exists for historical reasons: HTML form encoding predates and diverges from the generic URL spec, and that legacy convention is baked into how servers parse query strings.

The practical consequences:

• textCopy

  URLSearchParams
  encodes spaces as
  textCopy

  +
  (form-encoding rules). So
  textCopy

  new URLSearchParams({q: 'a b'}).toString()
  gives
  textCopy

  q=a+b
  .
• textCopy

  encodeURIComponent
  encodes spaces as
  textCopy

  %20
  and a
  textCopy

  +
  as
  textCopy

  %2B
  .
• Both
  textCopy

  a+b
  and
  textCopy

  a%20b
  decode to
  textCopy

  a b
  on a well-behaved server reading a query string, but a server reading a path will treat
  textCopy

  +
  as a literal plus.

The classic failure: a user searches for

. You encode it with , getting , which is correct. But if instead you only escaped spaces and left the pluses, the server sees , treats both pluses as spaces, and searches for (C followed by two spaces). The query silently returns the wrong results with no error anywhere.

The reverse failure: you store a value like

and round-trip it through a query string. If your encoder used for the space but you decode with form-decoding rules, the literal in gets turned into a space, and you read back .

How to stay safe

• Pick one tool for a given context and let it own both encoding and decoding. If you build query strings with
  textCopy

  URLSearchParams
  , parse them with
  textCopy

  URLSearchParams
  too, and the
  textCopy

  +
  /space round-trip stays consistent.
• Never mix: don't encode with
  textCopy

  encodeURIComponent
  and decode by manually replacing
  textCopy

  +
  with a space, or vice versa.
• When debugging, remember that a
  textCopy

  +
  in a URL is ambiguous on sight. You cannot tell whether it means "space" or "literal plus" without knowing which part of the URL it's in and which convention produced it.

If you ever need to eyeball what a particular string encodes to, or decode a captured URL to see what's really in it, our URL encoder and decoder runs entirely in your browser so nothing you paste leaves your machine. It's a quick way to confirm whether that mysterious

in a log is a literal plus or a botched space.

A short checklist

When you're encoding a URL, run through this:

1. Am I encoding a whole URL or a piece of one? Whole URL is rare; you almost always want to encode pieces with
   textCopy

   encodeURIComponent
   and assemble them.
2. Are reserved characters acting as structure or data? If
   textCopy

   &
   ,
   textCopy

   =
   ,
   textCopy

   /
   ,
   textCopy

   ?
   , or
   textCopy

   #
   are data inside a value, they must be escaped.
3. Path or query? Decide before you pick how spaces are handled. In doubt,
   textCopy

   %20
   is safe in both contexts.
4. Same tool in and out. Encode and decode with matching conventions so
   textCopy

   +
   and
   textCopy

   %2B
   round-trip correctly.
5. Prefer the built-ins.
   textCopy

   URLSearchParams
   and the
   textCopy

   URL
   API eliminate most hand-encoding mistakes.

Percent-encoding looks fiddly, but it reduces to one idea: characters that have meaning to the URL must be escaped when used as data, and there are two slightly different conventions for spaces depending on where you are. Internalize those two facts, lean on

and , and the whole class of encoding bugs mostly disappears.