HTML Reference Β· Characters and Codes
URL Encoding Reference
Percent-encoding reference: how every special ASCII character is encoded by encodeURIComponent, encodeURI and HTML forms, space handling, and UTF-8 examples.
A URL may contain only a limited set of ASCII characters. Anything else, such as a space, a character that has a special job in the URL, or any non-ASCII letter, is written with percent-encoding: a % followed by two hexadecimal digits for each byte of the character's UTF-8 encoding.
https://example.com/search?q=fish%20%26%20chips β q = "fish & chips" https://example.com/wiki/Caf%C3%A9 β path = "/wiki/CafΓ©"
Characters fall into three groups:
| Group | Characters | Rule |
|---|---|---|
| Unreserved | AβZ aβz 0β9 - . _ ~ |
Never need encoding. Encoding them is allowed but pointless. |
| Reserved | : / ? # [ ] @ ! $ & ' ( ) * + , ; = |
Have a structural meaning. Encode them when they are data, such as an & inside a search term. |
| Everything else | space, " % < > \ ^ ` { | }, control characters and all non-ASCII characters |
Must always be encoded. |
Try it
Type any text to see how each JavaScript function and HTML form encoding treats it.
ASCII characters that need encoding
The table lists every printable ASCII character except the unreserved ones. "Unchanged" means that method leaves the character as it is.
encodeURIComponent()is for one piece of a URL, such as a query value or a path segment. It escapes everything except unreserved characters and! ' ( ) *.encodeURI()is for a whole URL. It keeps reserved characters such as/,?and&so the URL keeps working, which also means it will not protect data that contains them.- Form encoding is the
application/x-www-form-urlencodedformat that HTML forms andURLSearchParamsproduce. It turns spaces into+and escapes everything except letters, digits and* - . _, so it even escapes~as%7E.
| Character | encodeURIComponent() |
encodeURI() |
Form encoding | Role in a URL |
|---|---|---|---|---|
| (space) | %20 |
%20 |
+ |
Not allowed; must always be encoded |
| ! | unchanged | unchanged | %21 |
Sub-delimiter (reserved, rarely special) |
| " | %22 |
%22 |
%22 |
Not allowed in URLs |
| # | %23 |
unchanged | %23 |
Starts the fragment |
| $ | %24 |
unchanged | %24 |
Sub-delimiter (reserved, rarely special) |
| % | %25 |
%25 |
%25 |
Starts a percent-escape, so a literal % must be escaped |
| & | %26 |
unchanged | %26 |
Separates query parameters |
| ' | unchanged | unchanged | %27 |
Sub-delimiter (reserved, rarely special) |
| ( | unchanged | unchanged | %28 |
Sub-delimiter (reserved, rarely special) |
| ) | unchanged | unchanged | %29 |
Sub-delimiter (reserved, rarely special) |
| * | unchanged | unchanged | unchanged | Sub-delimiter (reserved, rarely special) |
| + | %2B |
unchanged | %2B |
Means a space in form-encoded query strings |
| , | %2C |
unchanged | %2C |
Sub-delimiter, sometimes used to separate list values |
| / | %2F |
unchanged | %2F |
Separates path segments |
| : | %3A |
unchanged | %3A |
Ends the scheme (https:) and separates host from port |
| ; | %3B |
unchanged | %3B |
Sub-delimiter, used for parameters in some paths |
| < | %3C |
%3C |
%3C |
Not allowed in URLs |
| = | %3D |
unchanged | %3D |
Separates a query name from its value |
| > | %3E |
%3E |
%3E |
Not allowed in URLs |
| ? | %3F |
unchanged | %3F |
Starts the query string |
| @ | %40 |
unchanged | %40 |
Separates user info from the host |
| [ | %5B |
%5B |
%5B |
Wraps IPv6 addresses in the host |
| \ | %5C |
%5C |
%5C |
Not allowed; browsers treat it like / in http(s) URLs |
| ] | %5D |
%5D |
%5D |
Wraps IPv6 addresses in the host |
| ^ | %5E |
%5E |
%5E |
Not allowed in URLs |
| ` | %60 |
%60 |
%60 |
Not allowed in URLs |
| { | %7B |
%7B |
%7B |
Not allowed in URLs |
| | | %7C |
%7C |
%7C |
Not allowed in URLs |
| } | %7D |
%7D |
%7D |
Not allowed in URLs |
Spaces: %20 or +?
Both are correct, but in different places:
%20means a space anywhere in a URL: in the path, the query and the fragment.+means a space only inside a form-encoded query string (?q=red+shoes). In a path,+is just a plus sign, so/c++stays/c++.- Because of that rule, a real plus sign in form data must be sent as
%2B. If you build query strings by hand and forget,1+1=2arrives on the server as1 1=2. - Never put a raw space in a link. Browsers usually repair
href="my file.pdf"for you, but the HTML is invalid and other tools may break on it.
Non-ASCII characters (UTF-8)
Non-ASCII characters are first converted to their UTF-8 bytes, and each byte is then written as %XX. A character can therefore turn into two, three or four escapes.
| Character | Name | Code point | UTF-8 bytes | Percent-encoded |
|---|---|---|---|---|
| Γ© | Latin small e with acute | U+00E9 | C3 A9 |
%C3%A9 |
| ΓΌ | Latin small u with diaeresis | U+00FC | C3 BC |
%C3%BC |
| Γ± | Latin small n with tilde | U+00F1 | C3 B1 |
%C3%B1 |
| Γ | German sharp s | U+00DF | C3 9F |
%C3%9F |
| Γ§ | Latin small c with cedilla | U+00E7 | C3 A7 |
%C3%A7 |
| ΓΈ | Latin small o with stroke | U+00F8 | C3 B8 |
%C3%B8 |
| Β£ | Pound sign | U+00A3 | C2 A3 |
%C2%A3 |
| β¬ | Euro sign | U+20AC | E2 82 AC |
%E2%82%AC |
| Β© | Copyright sign | U+00A9 | C2 A9 |
%C2%A9 |
| Β° | Degree sign | U+00B0 | C2 B0 |
%C2%B0 |
| β | En dash | U+2013 | E2 80 93 |
%E2%80%93 |
| β | Right single quote | U+2019 | E2 80 99 |
%E2%80%99 |
| β | Rightwards arrow | U+2192 | E2 86 92 |
%E2%86%92 |
| Ξ© | Greek capital omega | U+03A9 | CE A9 |
%CE%A9 |
| ΠΆ | Cyrillic small zhe | U+0436 | D0 B6 |
%D0%B6 |
| Χ© | Hebrew shin | U+05E9 | D7 A9 |
%D7%A9 |
| Ω | Arabic meem | U+0645 | D9 85 |
%D9%85 |
| ΰ€¨ | Devanagari na | U+0928 | E0 A4 A8 |
%E0%A4%A8 |
| δΈ | CJK βmiddleβ | U+4E2D | E4 B8 AD |
%E4%B8%AD |
| ζ₯ | CJK βsun/dayβ | U+65E5 | E6 97 A5 |
%E6%97%A5 |
| ν | Hangul han | U+D55C | ED 95 9C |
%ED%95%9C |
| γ | Hiragana a | U+3042 | E3 81 82 |
%E3%81%82 |
| π | Grinning face emoji | U+1F600 | F0 9F 98 80 |
%F0%9F%98%80 |
| π | Thumbs up emoji | U+1F44D | F0 9F 91 8D |
%F0%9F%91%8D |
Browsers display many of these URLs in their readable form in the address bar, but they send the percent-encoded form over the network. Domain names are different: they use Punycode instead of percent-encoding, so cafΓ©.example is sent as xn--caf-dma.example.
Usage notes
- Encode values, not whole URLs. Build URLs from parts:
'/search?q=' + encodeURIComponent(term). RunningencodeURIComponent()on a full URL breaks it (https%3A%2F%2Fβ¦). - Prefer the
URLandURLSearchParamsAPIs. They encode and decode for you:url.searchParams.set('q', 'fish & chips'). - Don't encode twice. Encoding
%20again gives%2520. Decode with the matching function, and only once. - Percent-encoding is not HTML escaping. Inside an
hrefattribute, a literal&is safest written as&in your HTML source:href="?a=1&b=2". The browser first decodes the HTML, then uses the URL. - Hex digits are case-insensitive.
%c3%a9and%C3%A9mean the same thing; uppercase is the usual style.
Related
- ASCII table β codes for every ASCII character
- Character sets β how UTF-8 encodes characters as bytes
- HTTP methods β how forms send data with GET and POST
- Lesson: URL Encoding
- Lesson: Forms
- Lesson: Links in Depth