Revision 1089229 of FormData

<p>{{APIRef("XMLHttpRequest")}}</p>

<p>The <strong><code>FormData</code></strong> interface provides a way to easily construct a set of key/value pairs representing form fields and their values, which can then be easily sent using the {{domxref("XMLHttpRequest.send()")}} method. It uses the same format a form would use if the encoding type were set to <code>"multipart/form-data"</code>.</p>

<p>An object implementing <code>FormData</code> can directly be used in a {{jsxref("Statements/for...of", "for...of")}} structure, instead of {{domxref('FormData.entries()', 'entries()')}}: <code>for (var p of myFormData)</code> is equivalent to <code>for (var p of myFormData.entries())</code>.</p>

<div class="note">
<p><strong>Note</strong>: This feature is available in <a href="/en-US/docs/Web/API/Web_Workers_API">Web Workers</a>.</p>
</div>

<h2 id="Constructor">Constructor</h2>

<dl>
 <dt>{{domxref("FormData.FormData","FormData()")}}</dt>
 <dd>Creates a new <code>FormData</code> object.</dd>
</dl>

<h2 id="Methods">Methods</h2>

<dl>
 <dt>{{domxref("FormData.append()")}}</dt>
 <dd>Appends a new value onto an existing key inside a <code>FormData</code> object, or adds the key if it does not already exist.</dd>
 <dt>{{domxref("FormData.delete()")}}</dt>
 <dd>Deletes a key/value pair from a <code>FormData</code> object.</dd>
 <dt>{{domxref("FormData.entries()")}}</dt>
 <dd>Returns an {{jsxref("Iteration_protocols","iterator")}} allowing to go through all key/value pairs contained in this object.</dd>
 <dt>{{domxref("FormData.get()")}}</dt>
 <dd>Returns the first value associated with a given key from within a <code>FormData</code> object.</dd>
 <dt>{{domxref("FormData.getAll()")}}</dt>
 <dd>Returns an array of all the values associated with a given key from within a <code>FormData</code>.</dd>
 <dt>{{domxref("FormData.has()")}}</dt>
 <dd>Returns a boolean stating whether a <code>FormData</code> object contains a certain key/value pair.</dd>
 <dt>{{domxref("FormData.keys()")}}</dt>
 <dd>Returns an {{jsxref("Iteration_protocols", "iterator")}} allowing to go through all keys of the key/value pairs contained in this object.</dd>
 <dt>{{domxref("FormData.set()")}}</dt>
 <dd>Sets a new value for an existing key inside a <code>FormData </code>object, or adds the key/value if it does not already exist.</dd>
 <dt>{{domxref("FormData.values()")}}</dt>
 <dd>Returns an {{jsxref("Iteration_protocols", "iterator")}} allowing to go through all values of the key/value pairs contained in this object.</dd>
</dl>

<h2 id="Specifications">Specifications</h2>

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Status</th>
   <th scope="col">Comment</th>
  </tr>
  <tr>
   <td>{{SpecName('XMLHttpRequest','#interface-formdata','FormData')}}</td>
   <td>{{Spec2('XMLHttpRequest')}}</td>
   <td>FormData defined in XHR spec</td>
  </tr>
 </tbody>
</table>

<h2 id="Browser_compatibility">Browser compatibility</h2>

<div>{{CompatibilityTable}}</div>

<div id="compat-desktop">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Chrome</th>
   <th>Firefox (Gecko)</th>
   <th>Internet Explorer</th>
   <th>Opera</th>
   <th>Safari</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>{{CompatChrome(7.0)}}</td>
   <td>{{CompatGeckoDesktop("2.0")}}<sup>[1]</sup></td>
   <td>10</td>
   <td>12</td>
   <td>5</td>
  </tr>
  <tr>
   <td>append with filename</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop("22.0")}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td><code>delete()</code>, <code>get()</code>, <code>getAll()</code>, <code>has()</code>, <code>set()</code></td>
   <td>{{CompatChrome(50.0)}}</td>
   <td>{{CompatGeckoDesktop("39.0")}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
  </tr>
  <tr>
   <td><code>entries()</code>, <code>keys()</code>, <code>values()</code>, and support of <code>for...of</code></td>
   <td>{{CompatChrome(50.0)}}</td>
   <td>{{CompatGeckoDesktop("44.0")}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
  </tr>
  <tr>
   <td>Available in web workers</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoDesktop("39.0")}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatNo}}</td>
  </tr>
 </tbody>
</table>
</div>

<div id="compat-mobile">
<table class="compat-table">
 <tbody>
  <tr>
   <th>Feature</th>
   <th>Android</th>
   <th>Android Webview</th>
   <th>Firefox Mobile (Gecko)</th>
   <th>Firefox OS (Gecko)</th>
   <th>IE Mobile</th>
   <th>Opera Mobile</th>
   <th>Safari Mobile</th>
   <th>Chrome for Android</th>
  </tr>
  <tr>
   <td>Basic support</td>
   <td>3.0<sup>[2]</sup></td>
   <td>{{CompatVersionUnknown}}<sup>[2]</sup></td>
   <td>{{CompatGeckoMobile("2.0")}}<sup>[1]</sup></td>
   <td>1.0.1</td>
   <td>{{CompatUnknown}}</td>
   <td>12</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td>append with filename</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatGeckoMobile("22.0")}}</td>
   <td>1.2</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
  <tr>
   <td><code>delete()</code>, <code>get()</code>, <code>getAll()</code>, <code>has()</code>, <code>set()</code></td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatChrome(50.0)}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatChrome(50.0)}}</td>
  </tr>
  <tr>
   <td><code>entries()</code>, <code>keys()</code>, <code>values()</code>, and support of <code>for...of</code></td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(50.0)}}</td>
   <td>{{CompatGeckoMobile("44.0")}}</td>
   <td>2.5</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatUnknown}}</td>
   <td>{{CompatChrome(50.0)}}</td>
  </tr>
  <tr>
   <td>Available in web workers</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatVersionUnknown}}</td>
   <td>{{CompatNo}}</td>
   <td>{{CompatVersionUnknown}}</td>
  </tr>
 </tbody>
</table>
</div>

<p>[1] Prior to Gecko 7.0 {{geckoRelease("7.0")}}, if you specified a {{domxref("Blob")}} as the data to append to the object, the filename reported in the "Content-Disposition" HTTP header was an empty string; this resulted in errors being reported by some servers. Starting from Gecko 7.0, the filename "blob" is sent.</p>

<p>[2] XHR in Android 4.0 sends empty content for <code>FormData</code> with <code>blob</code>.</p>

<h2 id="See_also">See also</h2>

<ul>
 <li>{{domxref("XMLHTTPRequest")}}</li>
 <li><a href="/en-US/docs/Web/API/XMLHttpRequest/Using_XMLHttpRequest">Using XMLHttpRequest</a></li>
 <li><a href="/en-US/docs/Web/API/FormData/Using_FormData_Objects">Using FormData objects</a></li>
 <li>{{HTMLElement("Form")}}</li>
</ul>