FormData

  • Revision slug: DOM/XMLHttpRequest/FormData
  • Revision title: FormData
  • Revision id: 355711
  • Created:
  • Creator: evilpie
  • Is current revision? No
  • Comment

Revision Content

XMLHttpRequest Level 2 adds support for the new FormData interface. FormData objects provide 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 XMLHttpRequest send() method.

It uses the same format a form would use if the encoding type were set to "multipart/form-data".

For details on how to use the FormData object, see Using FormData objects.

Constructor

new FormData (optional HTMLFormElement form)

Parameters

form
(optional) HTML Form Element {{HTMLElement("form")}} to send for keys/values. It will also encode file input content.

Methods

append()

Appends a key/value pair to the FormData object.

void append(DOMString name, Blob value, optional DOMString filename);
void append(DOMString name, DOMString value);
Parameters
name
The name of the field whose data is contained in value.
value
The field's value. Can be a {{ domxref("Blob") }}, {{ domxref("File") }}, or a string, if neither, the value is converted to a string.
filename
(optional) The filename reported to the server, when a {{ domxref("Blob") }} or {{ domxref("File") }} is passed as second paramter. The default filename for {{domxref("Blob")}} objects is "blob".

Note: If you specify a {{ domxref("Blob") }} as the data to append to the FormData object, the filename that will be reported to the server in the "Content-Disposition" header used to vary from browser to browser.

Browser compatibility

{{ CompatibilityTable() }}

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 7+ {{ CompatGeckoDesktop("2.0") }} 10+ 12+ 5+
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support 3.0 {{ CompatGeckoMobile("2.0") }} {{ CompatUnknown() }}

12+

{{ CompatUnknown() }}

Gecko notes

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 in Gecko 7.0, the filename "blob" is sent.

Specification

See also

Revision Source

<p>XMLHttpRequest Level 2 adds support for the new <code>FormData</code> interface. <code>FormData</code> objects provide 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 XMLHttpRequest <a href="/en/DOM/XMLHttpRequest#send()" title="en/XMLHttpRequest#send()"><code>send()</code></a>&nbsp;method.</p>
<p>It uses the same format a form would use if the encoding type were set to "multipart/form-data".</p>
<p>For details on how to use the <code>FormData</code> object, see <a href="/en/DOM/XMLHttpRequest/FormData/Using_FormData_Objects" title="en/DOM/XMLHttpRequest/FormData/Using_FormData_objects">Using FormData objects</a>.</p>
<h2 id="Syntax" name="Syntax">Constructor</h2>
<pre class="syntaxbox">
<code>new FormData (optional </code><code>HTMLFormElement form</code><code>)</code></pre>
<h3 id="Parameters" name="Parameters">Parameters</h3>
<dl>
  <dt>
    <code>form</code></dt>
  <dd>
    (optional) HTML Form Element {{HTMLElement("form")}} to send for keys/values. It will also encode file input content.</dd>
</dl>
<h2 id="Methods">Methods</h2>
<h3 id="append()">append()</h3>
<p>Appends a key/value pair to the <code>FormData</code> object.</p>
<pre>
void <a href="/en/DOM/XMLHttpRequest/FormData#append()" title="en/DOM/XMLHttpRequest/FormData#append()">append</a>(DOMString name, Blob value, optional DOMString filename);
void <a href="/en/DOM/XMLHttpRequest/FormData#append()" title="en/DOM/XMLHttpRequest/FormData#append()">append</a>(DOMString name, DOMString value);</pre>
<h6 id="Parameters">Parameters</h6>
<dl>
  <dt>
    <code>name</code></dt>
  <dd>
    The name of the field whose data is contained in <code>value</code>.</dd>
  <dt>
    <code>value</code></dt>
  <dd>
    The field's value. Can be a {{ domxref("Blob") }}, {{ domxref("File") }}, or a string, if neither, the value is converted to a string.</dd>
  <dt>
    <code>filename</code></dt>
  <dd>
    (optional) The filename reported to the server, when a {{ domxref("Blob") }} or {{ domxref("File") }} is passed as second paramter. The default filename for {{domxref("Blob")}} objects is "blob".</dd>
</dl>
<div class="note">
  <p><strong>Note:</strong> If you specify a {{ domxref("Blob") }} as the data to append to the <code>FormData</code> object, the filename that will be reported to the server in the "Content-Disposition" header used to vary from browser to browser.</p>
</div>
<h2 id="Browser_compatibility">Browser compatibility</h2>
<p>{{ CompatibilityTable() }}</p>
<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>7+</td>
        <td>{{ CompatGeckoDesktop("2.0") }}</td>
        <td>10+</td>
        <td>12+</td>
        <td>5+</td>
      </tr>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Firefox Mobile (Gecko)</th>
        <th>IE Mobile</th>
        <th>Opera Mobile</th>
        <th>Safari Mobile</th>
      </tr>
      <tr>
        <td>Basic support</td>
        <td>3.0</td>
        <td>{{ CompatGeckoMobile("2.0") }}</td>
        <td>{{ CompatUnknown() }}</td>
        <td>
          <p>12+</p>
        </td>
        <td>{{ CompatUnknown() }}</td>
      </tr>
    </tbody>
  </table>
</div>
<h3 id="Gecko_notes">Gecko notes</h3>
<p>Prior to Gecko 7.0 {{ geckoRelease("7.0") }}, if you specified a {{ domxref("Blob") }}&nbsp;as the data to append to the object, the filename reported in the "Content-Disposition"&nbsp;HTTP header was an empty string; this resulted in errors being reported by some servers. Starting in&nbsp;Gecko 7.0, the filename "blob" is sent.</p>
<h2 id="Specification" name="Specification">Specification</h2>
<ul>
  <li><a class="external" href="http://www.w3.org/TR/XMLHttpRequest2/#interface-formdata" title="http://www.w3.org/TR/XMLHttpRequest2/#interface-formdata">W3C Specification</a></li>
  <li><a href="http://xhr.spec.whatwg.org/#interface-formdata" title="http://xhr.spec.whatwg.org/#interface-formdata">WHATWG Specification</a></li>
</ul>
<h2 id="See_also">See also</h2>
<ul>
  <li>{{domxref("XMLHTTPRequest")}}</li>
  <li><a href="/en/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="En/Using XMLHttpRequest">Using XMLHttpRequest</a></li>
  <li><a href="/en/DOM/XMLHttpRequest/FormData/Using_FormData_Objects" title="en/DOM/XMLHttpRequest/FormData/Using_FormData_objects">Using FormData objects</a></li>
  <li>{{HTMLElement("Form")}}</li>
</ul>
Revert to this revision