mozilla

Revision 432505 of encodeURIComponent()

  • Revision slug: Web/JavaScript/Reference/Global_Objects/encodeURIComponent
  • Revision title: encodeURIComponent
  • Revision id: 432505
  • Created:
  • Creator: Brettz9
  • Is current revision? No
  • Comment

Revision Content

Summary

Encodes a Uniform Resource Identifier (URI) component by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character (will only be four escape sequences for characters composed of two "surrogate" characters).

Core Global Method
Implemented in JavaScript ?
ECMAScript Edition ECMAScript 3rd Edition

Syntax

var encoded = encodeURIComponent(str);

Parameters

str
A component of a URI.

Description

encodeURIComponent escapes all characters except the following: alphabetic, decimal digits, - _ . ! ~ * ' ( )

Note that an error will be thrown if one attempts to encode a surrogate which is not part of a high-low pair, e.g.,

alert(encodeURIComponent('\uD800\uDFFF')); // high-low pair ok
alert(encodeURIComponent('\uD800')); // lone high surrogate throws "URIError: malformed URI sequence"
alert(encodeURIComponent('\uDFFF')); // lone low surrogate throws "URIError: malformed URI sequence"

To avoid unexpected requests to the server, you should call encodeURIComponent on any user-entered parameters that will be passed as part of a URI. For example, a user could type "Thyme &time=again" for a variable comment. Not using encodeURIComponent on this variable will give comment=Thyme%20&time=again. Note that the ampersand and the equal sign mark a new key and value pair. So instead of having a POST comment key equal to "Thyme &time=again", you have two POST keys, one equal to "Thyme " and another (time) equal to again.

For application/x-www-form-urlencoded (POST), per http://www.w3.org/TR/html401/interac...m-content-type, spaces are to be replaced by '+', so one may wish to follow a encodeURIComponent replacement with an additional replacement of "%20" with "+".

If one wishes to be more stringent in adhering to RFC 3986 (which reserves !, ', (, ), and *), even though these characters have no formalized URI delimiting uses, the following can be safely used:

function fixedEncodeURIComponent (str) {
  return encodeURIComponent(str).replace(/[!'()]/g, escape).replace(/\*/g, "%2A");
}

See also

Revision Source

<h2 id="Summary" name="Summary">Summary</h2>
<p>Encodes a Uniform Resource Identifier (URI) component by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character (will only be four escape sequences for characters composed of two "surrogate" characters).</p>
<table class="standard-table">
  <thead>
    <tr>
      <th class="header" colspan="2">Core Global Method</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Implemented in</td>
      <td>JavaScript ?</td>
    </tr>
    <tr>
      <td>ECMAScript Edition</td>
      <td>ECMAScript 3rd Edition</td>
    </tr>
  </tbody>
</table>
<h2 id="Syntax" name="Syntax">Syntax</h2>
<pre class="syntaxbox">
var encoded = encodeURIComponent(<em>str</em>);</pre>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<dl>
  <dt>
    <code>str</code></dt>
  <dd>
    A component of a URI.</dd>
</dl>
<h2 id="Description" name="Description">Description</h2>
<p><code>encodeURIComponent</code> escapes all characters except the following: alphabetic, decimal digits, <code>- _ .&nbsp;! ~ * ' ( )</code></p>
<p>Note that an error will be thrown if one attempts to encode a surrogate which is not part of a high-low pair, e.g.,</p>
<pre class="brush: js">
alert(encodeURIComponent('\uD800\uDFFF')); // high-low pair ok
alert(encodeURIComponent('\uD800')); // lone high surrogate throws "URIError: malformed URI sequence"
alert(encodeURIComponent('\uDFFF')); // lone low surrogate throws "URIError: malformed URI sequence"
</pre>
<p>To avoid unexpected requests to the server, you should call <code>encodeURIComponent</code> on any user-entered parameters that will be passed as part of a URI. For example, a user could type "<code>Thyme &amp;time=again</code>" for a variable <code>comment</code>. Not using <code>encodeURIComponent</code> on this variable will give <code>comment=Thyme%20&amp;time=again</code>. Note that the ampersand and the equal sign mark a new key and value pair. So instead of having a POST <code>comment</code> key equal to "<code>Thyme &amp;time=again</code>", you have two POST keys, one equal to "<code>Thyme </code>" and another (<code>time</code>) equal to <code>again</code>.</p>
<p>For <code>application/x-www-form-urlencoded</code> (POST), per <a class="external" href="http://www.w3.org/TR/html401/interact/forms.html#form-content-type" rel="freelink">http://www.w3.org/TR/html401/interac...m-content-type</a>, spaces are to be replaced by '+', so one may wish to follow a <code>encodeURIComponent</code> replacement with an additional replacement of "%20" with "+".</p>
<p>If one wishes to be more stringent in adhering to <a class="external" href="http://tools.ietf.org/html/rfc3986" title="http://labs.apache.org/webarch/uri/rfc/rfc3986.html">RFC 3986</a> (which reserves !, ', (, ), and *), even though these characters have no formalized URI delimiting uses, the following can be safely used:</p>
<pre class="brush: js">
function fixedEncodeURIComponent (str) {
  return encodeURIComponent(str).replace(/[!'()]/g, escape).replace(/\*/g, "%2A");
}
</pre>
<h2 id="See_also" name="See_also">See also</h2>
<ul>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/decodeURI" title="JavaScript/Reference/Global_Functions/decodeURI">decodeURI</a></li>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/decodeURIComponent" title="JavaScript/Reference/Global_Functions/decodeURIComponent">decodeURIComponent</a></li>
  <li><a href="/en-US/docs/JavaScript/Reference/Global_Objects/encodeURI" title="JavaScript/Reference/Global_Objects/encodeURI">encodeURI</a></li>
</ul>
<!-- languages({
	"fr": "fr/R\u00e9f\u00e9rence_de_JavaScript_1.5_Core/Fonctions_globales/encodeURIComponent",
	"zh-cn":"zh-cn/JavaScript/Reference/Global_Objects/encodeURIComponent"
}) -->
Revert to this revision