Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 122 · Links and Navigation

URL Encoding

Learn why URLs need percent-encoding, which characters are reserved, %20 versus + for spaces, how UTF-8 encodes non-English text, and how encodeURIComponent works.

A URL can only contain a small, safe set of characters. Yet people search for "crème brûlée", name files "Summer Menu.pdf" and send messages that contain & and ?. URL encoding, also called percent-encoding, is how all of those characters travel safely inside an address.

You don't need to memorize code tables. You need to know why encoding exists, which characters need it, and which JavaScript functions do the work. That is what this lesson covers.

Why URLs need encoding

Some characters have a special job inside a URL. Take this search address:

TEXT
https://example.com/search?q=salt&pepper

Is that a search for "salt&pepper"? Or a search for "salt" with a second, empty parameter called pepper? The browser and the server read it as the second, because & separates query parameters. To search for the literal text, the & must be encoded:

TEXT
https://example.com/search?q=salt%26pepper

Now %26 means "an ampersand that is part of the value", and the URL is no longer ambiguous.

Reserved and unreserved characters

The URL standard sorts characters into groups:

Group Characters Rule
Unreserved A–Z, a–z, 0–9, - . _ ~ Always safe. Never need encoding.
Reserved : / ? # [ ] @ ! $ & ' ( ) * + , ; = Have a structural meaning. Encode them when they are part of a value.
Everything else spaces, ", <, >, %, non-English letters, emoji… Must be encoded.

The reserved characters are what give a URL its shape: : after the scheme, / between folders, ? before the query, & and = inside it, # before the fragment. As long as they play those roles, leave them alone. Only encode them when they appear inside a piece of data.

How percent-encoding works

Each character to encode becomes a % followed by two hexadecimal digits, the value of the byte. A few you will meet often:

Character Encoded
space %20
! %21
# %23
% %25
& %26
+ %2B
/ %2F
? %3F
@ %40

Note that % itself must be encoded as %25, since it introduces every escape. Letters in the hex digits can be upper or lower case (%2f and %2F mean the same thing), but uppercase is the convention.

Non-English text: UTF-8 bytes

What about é, ж, 中 or 😀? These characters are first converted into UTF-8 bytes, and then each byte is percent-encoded. That is why a single character can turn into several escapes:

Character UTF-8 bytes Encoded
é C3 A9 %C3%A9
€ E2 82 AC %E2%82%AC
😀 F0 9F 98 80 %F0%9F%98%80

Type anything into the box below to see its bytes:

Characters to UTF-8 bytes

Notice that the plain letters C, a and f are left alone: they are unreserved. Read Character Encoding and UTF-8 to learn how UTF-8 decides how many bytes each character needs.

Domain names work differently. The host part of a URL doesn't use percent-encoding. Internationalized domain names such as bücher.example are converted to an ASCII form called Punycode (xn--bcher-kva.example). Browsers do this for you, and most show the readable version in the address bar.

Spaces: %20 or +?

You will see spaces written two ways, and the difference trips up many developers:

  • %20 is the standard encoding of a space and works anywhere in a URL, including paths: /files/summer%20menu.pdf.
  • + means a space only in a query string that uses the form encoding (application/x-www-form-urlencoded). That is the format HTML forms produce when they submit with GET: ?q=summer+menu.

In a path, a + is just a plus sign. And because + can mean a space in a query string, a real plus sign there must be encoded as %2B. Otherwise "C++" turns into "C " (with two spaces) on the server.

The safest habit: name files without spaces, and let functions do the encoding for everything else.

Encoding in JavaScript

JavaScript has built-in tools for each job:

  • encodeURIComponent(value) encodes one value, such as a search term or a file name. It encodes every reserved character, so the result is safe to drop between = and &, or between two /.
  • encodeURI(url) encodes a whole URL. It leaves reserved characters such as /, ?, & and # alone, because it assumes they are structure. Never use it on a single value.
  • URLSearchParams builds and reads query strings, and uses + for spaces like an HTML form does.
  • decodeURIComponent() reverses encodeURIComponent().

Compare all three on the same text:

encodeURIComponent vs encodeURI vs URLSearchParams

Look at what encodeURI leaves untouched: &, /, ? and #. Put that output into a query string and it breaks into several parameters and a fragment. That is why individual values always go through encodeURIComponent or URLSearchParams.

Encoding in HTML attributes

Inside an href, you can usually write readable text and let the browser encode it. In a UTF-8 page, this link works:

HTML
<a href="https://example.com/recettes/crème-brûlée">Crème brûlée</a>

The browser converts the path to /recettes/cr%C3%A8me-br%C3%BBl%C3%A9e when it makes the request. Spaces, however, are invalid in a URL, so write %20 yourself, or better, avoid them.

There is one HTML-specific detail to know. & starts a character reference in HTML, such as &copy;. A query string like ?a=1&b=2 is fine in practice, but writing &amp; is always unambiguous and valid:

HTML
<a href="/search?q=tea&amp;sort=price">Teas sorted by price</a>

The browser decodes &amp; back to & before it ever uses the URL. You will learn more about references like that in HTML Entities.

Check your understanding

Quick check · 4 questions

of 4 answered You scored / 4 · perfect!

  1. 1. You want to search for the text 'rock & roll'. Which query string is correct?

    The & is part of the value, so it must become %26. Left raw, it would start a new parameter.
  2. 2. Why does a single é become %C3%A9 rather than one escape?

    Percent-encoding works on bytes. In UTF-8, é is the two bytes C3 and A9, so it becomes two escapes.
  3. 3. Which function should you use to encode a single search term before adding it to a URL?

    encodeURIComponent() encodes reserved characters like &, ? and # too. encodeURI() leaves them alone, and escape() is an obsolete function that mishandles non-ASCII text.
  4. 4. In which part of a URL does + mean a space?

    + stands for a space only in form-encoded query strings. Everywhere else it is a literal plus sign; %20 works everywhere.

Summary

  • URLs allow only a limited set of characters; others are percent-encoded as % plus two hex digits.
  • Reserved characters such as &, ?, # and / must be encoded when they appear inside a value.
  • Non-English characters are converted to UTF-8 bytes, and each byte is encoded.
  • A space is %20 anywhere, and + only in form-encoded query strings; a real + there must be %2B.
  • Use encodeURIComponent() or URLSearchParams for values; encodeURI() only for whole URLs.
  • In HTML, writing &amp; in an href is always safe.

Next lesson: Lists, the start of a new chapter on organizing content.