[{"data":1,"prerenderedAt":1085},["ShallowReactive",2],{"guide-url-encoding-guide":3},{"id":4,"title":5,"body":6,"date":1077,"description":1078,"extension":1079,"meta":1080,"navigation":576,"path":1081,"readingTime":586,"seo":1082,"stem":1083,"__hash__":1084},"guides\u002Fguides\u002Furl-encoding-guide.md","What Is URL Encoding? Complete Guide to Percent-Encoding",{"type":7,"value":8,"toc":1057},"minimark",[9,14,23,34,37,41,44,47,92,96,99,379,383,386,440,447,451,454,474,479,518,614,618,669,673,676,731,735,764,815,819,910,914,917,955,959,973,977,1016,1020,1041,1045,1053],[10,11,13],"h2",{"id":12},"what-is-url-encoding","What Is URL Encoding?",[15,16,17,18,22],"p",{},"URL encoding (also called percent-encoding) converts characters into a format that can safely travel across the internet. It replaces unsafe or reserved characters with a ",[19,20,21],"code",{},"%"," followed by two hexadecimal digits.",[15,24,25,26,29,30,33],{},"For example, a space becomes ",[19,27,28],{},"%20",", and an ampersand becomes ",[19,31,32],{},"%26",".",[15,35,36],{},"Every URL you click, every API request your app sends, and every form your users submit relies on URL encoding behind the scenes.",[10,38,40],{"id":39},"why-url-encoding-matters","Why URL Encoding Matters",[15,42,43],{},"URLs can only carry a limited set of ASCII characters. Anything outside that set — spaces, Unicode text, or special symbols — must be encoded before it enters a URL.",[15,45,46],{},"Without encoding:",[48,49,50,58,72,86],"ul",{},[51,52,53,57],"li",{},[54,55,56],"strong",{},"Spaces break URLs"," — they confuse browsers and servers",[51,59,60,63,64,67,68,71],{},[54,61,62],{},"Reserved characters change meaning"," — ",[19,65,66],{},"&"," splits query parameters, ",[19,69,70],{},"="," assigns values",[51,73,74,77,78,81,82,85],{},[54,75,76],{},"Unicode causes errors"," — non-ASCII characters like ",[19,79,80],{},"é"," or ",[19,83,84],{},"你好"," need encoding",[51,87,88,91],{},[54,89,90],{},"APIs reject bad input"," — unencoded payloads fail silently or return errors",[10,93,95],{"id":94},"reserved-characters","Reserved Characters",[15,97,98],{},"RFC 3986 defines characters with special meanings in URLs. These characters must be percent-encoded when used as data, not as delimiters:",[100,101,102,118],"table",{},[103,104,105],"thead",{},[106,107,108,112,115],"tr",{},[109,110,111],"th",{},"Character",[109,113,114],{},"Encoded",[109,116,117],{},"Purpose in URLs",[119,120,121,137,152,166,179,193,207,221,235,249,263,278,293,307,321,336,350,365],"tbody",{},[106,122,123,129,134],{},[124,125,126],"td",{},[19,127,128],{},"!",[124,130,131],{},[19,132,133],{},"%21",[124,135,136],{},"Sub-delim",[106,138,139,144,149],{},[124,140,141],{},[19,142,143],{},"#",[124,145,146],{},[19,147,148],{},"%23",[124,150,151],{},"Fragment identifier",[106,153,154,159,164],{},[124,155,156],{},[19,157,158],{},"$",[124,160,161],{},[19,162,163],{},"%24",[124,165,136],{},[106,167,168,172,176],{},[124,169,170],{},[19,171,66],{},[124,173,174],{},[19,175,32],{},[124,177,178],{},"Query parameter separator",[106,180,181,186,191],{},[124,182,183],{},[19,184,185],{},"'",[124,187,188],{},[19,189,190],{},"%27",[124,192,136],{},[106,194,195,200,205],{},[124,196,197],{},[19,198,199],{},"(",[124,201,202],{},[19,203,204],{},"%28",[124,206,136],{},[106,208,209,214,219],{},[124,210,211],{},[19,212,213],{},")",[124,215,216],{},[19,217,218],{},"%29",[124,220,136],{},[106,222,223,228,233],{},[124,224,225],{},[19,226,227],{},"*",[124,229,230],{},[19,231,232],{},"%2A",[124,234,136],{},[106,236,237,242,247],{},[124,238,239],{},[19,240,241],{},"+",[124,243,244],{},[19,245,246],{},"%2B",[124,248,136],{},[106,250,251,256,261],{},[124,252,253],{},[19,254,255],{},",",[124,257,258],{},[19,259,260],{},"%2C",[124,262,136],{},[106,264,265,270,275],{},[124,266,267],{},[19,268,269],{},"\u002F",[124,271,272],{},[19,273,274],{},"%2F",[124,276,277],{},"Path separator",[106,279,280,285,290],{},[124,281,282],{},[19,283,284],{},":",[124,286,287],{},[19,288,289],{},"%3A",[124,291,292],{},"Scheme\u002Fport separator",[106,294,295,300,305],{},[124,296,297],{},[19,298,299],{},";",[124,301,302],{},[19,303,304],{},"%3B",[124,306,136],{},[106,308,309,313,318],{},[124,310,311],{},[19,312,70],{},[124,314,315],{},[19,316,317],{},"%3D",[124,319,320],{},"Query parameter assignment",[106,322,323,328,333],{},[124,324,325],{},[19,326,327],{},"?",[124,329,330],{},[19,331,332],{},"%3F",[124,334,335],{},"Query string start",[106,337,338,343,348],{},[124,339,340],{},[19,341,342],{},"@",[124,344,345],{},[19,346,347],{},"%40",[124,349,136],{},[106,351,352,357,362],{},[124,353,354],{},[19,355,356],{},"[",[124,358,359],{},[19,360,361],{},"%5B",[124,363,364],{},"IPv6 address",[106,366,367,372,377],{},[124,368,369],{},[19,370,371],{},"]",[124,373,374],{},[19,375,376],{},"%5D",[124,378,364],{},[10,380,382],{"id":381},"unreserved-characters","Unreserved Characters",[15,384,385],{},"These characters never need encoding:",[48,387,388,401,409,417,424,432],{},[51,389,390,393,394,397,398],{},[54,391,392],{},"Letters",": ",[19,395,396],{},"A–Z",", ",[19,399,400],{},"a–z",[51,402,403,393,406],{},[54,404,405],{},"Digits",[19,407,408],{},"0–9",[51,410,411,393,414],{},[54,412,413],{},"Hyphen",[19,415,416],{},"-",[51,418,419,393,422],{},[54,420,421],{},"Period",[19,423,33],{},[51,425,426,393,429],{},[54,427,428],{},"Underscore",[19,430,431],{},"_",[51,433,434,393,437],{},[54,435,436],{},"Tilde",[19,438,439],{},"~",[15,441,442,443,446],{},"RFC 3986 states that unreserved characters should ",[54,444,445],{},"not"," be encoded. Encoding them produces equivalent but longer URLs.",[10,448,450],{"id":449},"_20-vs-the-space-encoding-trap","%20 vs +: The Space Encoding Trap",[15,452,453],{},"Spaces in URLs present a historical ambiguity:",[48,455,456,463],{},[51,457,458,462],{},[54,459,460],{},[19,461,28],{}," — true percent-encoding per RFC 3986, valid everywhere in a URL",[51,464,465,469,470,473],{},[54,466,467],{},[19,468,241],{}," — legacy encoding from ",[19,471,472],{},"application\u002Fx-www-form-urlencoded",", valid only in query strings",[475,476,478],"h3",{"id":477},"when-to-use-each","When to use each",[48,480,481,489,499,509],{},[51,482,483,486,487],{},[54,484,485],{},"Path segments",": always use ",[19,488,28],{},[51,490,491,393,496,498],{},[54,492,493,494],{},"Query strings with ",[19,495,472],{},[19,497,241],{}," is the standard",[51,500,501,506,507],{},[54,502,493,503],{},[19,504,505],{},"multipart\u002Fform-data",": use ",[19,508,28],{},[51,510,511,514,515,517],{},[54,512,513],{},"REST API parameters",": prefer ",[19,516,28],{}," for safety",[519,520,525],"pre",{"className":521,"code":522,"language":523,"meta":524,"style":524},"language-javascript shiki shiki-themes github-light github-dark","\u002F\u002F JavaScript's built-in functions\nencodeURIComponent('hello world')  \u002F\u002F \"hello%20world\"\nencodeURI('hello world')           \u002F\u002F \"hello%20world\"\n\n\u002F\u002F Form encoding (application\u002Fx-www-form-urlencoded)\nnew URLSearchParams({ q: 'hello world' }).toString()\n\u002F\u002F \"q=hello+world\"\n","javascript","",[19,526,527,536,556,571,578,584,608],{"__ignoreMap":524},[528,529,532],"span",{"class":530,"line":531},"line",1,[528,533,535],{"class":534},"sJ8bj","\u002F\u002F JavaScript's built-in functions\n",[528,537,539,543,546,550,553],{"class":530,"line":538},2,[528,540,542],{"class":541},"sScJk","encodeURIComponent",[528,544,199],{"class":545},"sVt8B",[528,547,549],{"class":548},"sZZnC","'hello world'",[528,551,552],{"class":545},")  ",[528,554,555],{"class":534},"\u002F\u002F \"hello%20world\"\n",[528,557,559,562,564,566,569],{"class":530,"line":558},3,[528,560,561],{"class":541},"encodeURI",[528,563,199],{"class":545},[528,565,549],{"class":548},[528,567,568],{"class":545},")           ",[528,570,555],{"class":534},[528,572,574],{"class":530,"line":573},4,[528,575,577],{"emptyLinePlaceholder":576},true,"\n",[528,579,581],{"class":530,"line":580},5,[528,582,583],{"class":534},"\u002F\u002F Form encoding (application\u002Fx-www-form-urlencoded)\n",[528,585,587,591,594,597,599,602,605],{"class":530,"line":586},6,[528,588,590],{"class":589},"szBVR","new",[528,592,593],{"class":541}," URLSearchParams",[528,595,596],{"class":545},"({ q: ",[528,598,549],{"class":548},[528,600,601],{"class":545}," }).",[528,603,604],{"class":541},"toString",[528,606,607],{"class":545},"()\n",[528,609,611],{"class":530,"line":610},7,[528,612,613],{"class":534},"\u002F\u002F \"q=hello+world\"\n",[475,615,617],{"id":616},"common-mistake","Common mistake",[519,619,621],{"className":521,"code":620,"language":523,"meta":524,"style":524},"\u002F\u002F WRONG: Using + in path segments\nconst url = `\u002Fsearch\u002Fhello+world`  \u002F\u002F Server reads \"hello+world\" literally\n\n\u002F\u002F CORRECT: Use %20 in path segments\nconst url = `\u002Fsearch\u002Fhello%20world`  \u002F\u002F Server reads \"hello world\"\n",[19,622,623,628,646,650,655],{"__ignoreMap":524},[528,624,625],{"class":530,"line":531},[528,626,627],{"class":534},"\u002F\u002F WRONG: Using + in path segments\n",[528,629,630,633,637,640,643],{"class":530,"line":538},[528,631,632],{"class":589},"const",[528,634,636],{"class":635},"sj4cs"," url",[528,638,639],{"class":589}," =",[528,641,642],{"class":548}," `\u002Fsearch\u002Fhello+world`",[528,644,645],{"class":534},"  \u002F\u002F Server reads \"hello+world\" literally\n",[528,647,648],{"class":530,"line":558},[528,649,577],{"emptyLinePlaceholder":576},[528,651,652],{"class":530,"line":573},[528,653,654],{"class":534},"\u002F\u002F CORRECT: Use %20 in path segments\n",[528,656,657,659,661,663,666],{"class":530,"line":580},[528,658,632],{"class":589},[528,660,636],{"class":635},[528,662,639],{"class":589},[528,664,665],{"class":548}," `\u002Fsearch\u002Fhello%20world`",[528,667,668],{"class":534},"  \u002F\u002F Server reads \"hello world\"\n",[10,670,672],{"id":671},"encodeuricomponent-vs-encodeuri","encodeURIComponent vs encodeURI",[15,674,675],{},"JavaScript provides two encoding functions with different scopes:",[100,677,678,691],{},[103,679,680],{},[106,681,682,685,688],{},[109,683,684],{},"Function",[109,686,687],{},"Encodes",[109,689,690],{},"Leaves unencoded",[119,692,693,716],{},[106,694,695,699,710],{},[124,696,697],{},[19,698,561],{},[124,700,701,702,397,704,397,706,397,708],{},"Spaces, non-ASCII, ",[19,703,143],{},[19,705,327],{},[19,707,66],{},[19,709,70],{},[124,711,712,715],{},[19,713,714],{},":\u002F?#[]@!$&'()*+,;="," (URL structure chars)",[106,717,718,722,725],{},[124,719,720],{},[19,721,542],{},[124,723,724],{},"Spaces, non-ASCII, all reserved chars",[124,726,727,730],{},[19,728,729],{},"-_.!~*'()"," only",[475,732,734],{"id":733},"practical-guidelines","Practical guidelines",[48,736,737,745,752],{},[51,738,739,740,744],{},"Use ",[54,741,742],{},[19,743,561],{}," when encoding a complete URL",[51,746,739,747,751],{},[54,748,749],{},[19,750,542],{}," when encoding a single query parameter value",[51,753,754,755,757,758,760,761,763],{},"Never use ",[19,756,561],{}," on query values — it leaves ",[19,759,66],{}," and ",[19,762,70],{}," unencoded",[519,765,767],{"className":521,"code":766,"language":523,"meta":524,"style":524},"\u002F\u002F Encoding parts of a query string\nconst query = `q=${encodeURIComponent('JS & React')}&lang=${encodeURIComponent('en')}`\n\u002F\u002F \"q=JS%20%26%20React&lang=en\"\n",[19,768,769,774,810],{"__ignoreMap":524},[528,770,771],{"class":530,"line":531},[528,772,773],{"class":534},"\u002F\u002F Encoding parts of a query string\n",[528,775,776,778,781,783,786,788,790,793,795,798,800,802,805,807],{"class":530,"line":538},[528,777,632],{"class":589},[528,779,780],{"class":635}," query",[528,782,639],{"class":589},[528,784,785],{"class":548}," `q=${",[528,787,542],{"class":541},[528,789,199],{"class":548},[528,791,792],{"class":548},"'JS & React'",[528,794,213],{"class":548},[528,796,797],{"class":548},"}&lang=${",[528,799,542],{"class":541},[528,801,199],{"class":548},[528,803,804],{"class":548},"'en'",[528,806,213],{"class":548},[528,808,809],{"class":548},"}`\n",[528,811,812],{"class":530,"line":558},[528,813,814],{"class":534},"\u002F\u002F \"q=JS%20%26%20React&lang=en\"\n",[10,816,818],{"id":817},"common-encoding-examples","Common Encoding Examples",[100,820,821,833],{},[103,822,823],{},[106,824,825,828,830],{},[109,826,827],{},"Raw Value",[109,829,114],{},[109,831,832],{},"Context",[119,834,835,850,865,880,895],{},[106,836,837,842,847],{},[124,838,839],{},[19,840,841],{},"hello world",[124,843,844],{},[19,845,846],{},"hello%20world",[124,848,849],{},"Space in query",[106,851,852,857,862],{},[124,853,854],{},[19,855,856],{},"price=10&sale=5",[124,858,859],{},[19,860,861],{},"price%3D10%26sale%3D5",[124,863,864],{},"Ampersand\u002Fequal as data",[106,866,867,872,877],{},[124,868,869],{},[19,870,871],{},"\u002Fapi\u002Fusers",[124,873,874],{},[19,875,876],{},"%2Fapi%2Fusers",[124,878,879],{},"Slash as data value",[106,881,882,887,892],{},[124,883,884],{},[19,885,886],{},"café",[124,888,889],{},[19,890,891],{},"caf%C3%A9",[124,893,894],{},"Unicode character",[106,896,897,902,907],{},[124,898,899],{},[19,900,901],{},"hello@example",[124,903,904],{},[19,905,906],{},"hello%40example",[124,908,909],{},"At sign as data",[10,911,913],{"id":912},"browser-behavior","Browser Behavior",[15,915,916],{},"Modern browsers handle URL encoding automatically in several contexts:",[48,918,919,925,936,944],{},[51,920,921,924],{},[54,922,923],{},"Address bar",": Browsers display decoded URLs but send encoded URLs",[51,926,927,935],{},[54,928,929,760,932],{},[19,930,931],{},"fetch()",[19,933,934],{},"XMLHttpRequest",": Do not auto-encode your URL — you must encode it",[51,937,938,943],{},[54,939,940],{},[19,941,942],{},"\u003Ca href>",": Browsers auto-encode paths but not query strings consistently",[51,945,946,949,950,952,953,213],{},[54,947,948],{},"Form submission",": Uses ",[19,951,472],{}," rules (spaces → ",[19,954,241],{},[475,956,958],{"id":957},"what-you-need-to-handle-manually","What you need to handle manually",[48,960,961,964,967,970],{},[51,962,963],{},"Building API request URLs in JavaScript",[51,965,966],{},"Constructing URLs with dynamic path segments",[51,968,969],{},"Passing special characters as query parameter values",[51,971,972],{},"Sharing URLs that contain non-ASCII text",[10,974,976],{"id":975},"_5-best-practices","5 Best Practices",[978,979,980,988,994,1004,1010],"ol",{},[51,981,982,985,986],{},[54,983,984],{},"Always encode query parameter values"," with ",[19,987,542],{},[51,989,990,993],{},[54,991,992],{},"Don't double-encode"," — check if data is already encoded before encoding again",[51,995,996,397,1001,1003],{},[54,997,739,998,1000],{},[19,999,28],{}," for paths",[19,1002,241],{}," only for form-encoded query strings",[51,1005,1006,1009],{},[54,1007,1008],{},"Decode server-side"," before processing — never trust raw URL input",[51,1011,1012,1015],{},[54,1013,1014],{},"Validate decoded values"," — URL encoding is not sanitization",[10,1017,1019],{"id":1018},"related-guides","Related Guides",[48,1021,1022,1029,1035],{},[51,1023,1024],{},[1025,1026,1028],"a",{"href":1027},"\u002Fguides\u002Furl-encoding-vs-base64","URL Encoding vs Base64",[51,1030,1031],{},[1025,1032,1034],{"href":1033},"\u002Fguides\u002Fpercent-encoding-reference","Percent-Encoding Reference",[51,1036,1037],{},[1025,1038,1040],{"href":1039},"\u002Fguides\u002Fbase64-encoding-guide","Base64 Encoding Guide",[10,1042,1044],{"id":1043},"try-it-yourself","Try It Yourself",[15,1046,1047,1048,1052],{},"Encode and decode URLs instantly with our free ",[1025,1049,1051],{"href":1050},"\u002Ftools\u002Furl-encoder","URL Encoder\u002FDecoder"," tool. Paste any text or URL and get the correctly encoded result in one click.",[1054,1055,1056],"style",{},"html pre.shiki code .sJ8bj, html code.shiki .sJ8bj{--shiki-default:#6A737D;--shiki-dark:#6A737D}html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}",{"title":524,"searchDepth":538,"depth":538,"links":1058},[1059,1060,1061,1062,1063,1067,1070,1071,1074,1075,1076],{"id":12,"depth":538,"text":13},{"id":39,"depth":538,"text":40},{"id":94,"depth":538,"text":95},{"id":381,"depth":538,"text":382},{"id":449,"depth":538,"text":450,"children":1064},[1065,1066],{"id":477,"depth":558,"text":478},{"id":616,"depth":558,"text":617},{"id":671,"depth":538,"text":672,"children":1068},[1069],{"id":733,"depth":558,"text":734},{"id":817,"depth":538,"text":818},{"id":912,"depth":538,"text":913,"children":1072},[1073],{"id":957,"depth":558,"text":958},{"id":975,"depth":538,"text":976},{"id":1018,"depth":538,"text":1019},{"id":1043,"depth":538,"text":1044},"2026-05-27","Learn what URL encoding is, how percent-encoding works, and why it's essential for web development and API requests.","md",{"immutable":576},"\u002Fguides\u002Furl-encoding-guide",{"title":5,"description":1078},"guides\u002Furl-encoding-guide","cna022UHtwf5KV2Yp60DzAnk00nrQvENVc5MRXUlSTQ",1780401325684]