Revision 459771 of FormData

  • Revision slug: Web/API/FormData
  • Revision title: FormData
  • Revision id: 459771
  • Created:
  • Creator: mattflaschen
  • 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_inline}} 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, File value, optional DOMString filename);
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_inline}} 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+
append with filename {{CompatVersionUnknown}} {{CompatGeckoDesktop("22.0")}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}}
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support 3.0 {{CompatUnknown}} {{CompatGeckoMobile("2.0")}} {{CompatUnknown}}

12+

{{CompatUnknown}}
append with filename {{CompatUnknown}} {{CompatUnknown}} {{CompatGeckoDesktop("22.0")}} {{CompatUnknown}} {{CompatUnknown}} {{CompatUnknown}}

 

Note: XHR in Android 4.0 sends empty content for FormData with blob.

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-US/docs/DOM/XMLHttpRequest#send()" title="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-US/docs/DOM/XMLHttpRequest/FormData/Using_FormData_Objects" title="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_inline}} 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-US/docs/DOM/XMLHttpRequest/FormData#append()" title="DOM/XMLHttpRequest/FormData#append()">append</a>(DOMString name, File value, optional DOMString filename);
void <a href="/en-US/docs/DOM/XMLHttpRequest/FormData#append()" title="DOM/XMLHttpRequest/FormData#append()">append</a>(DOMString name, Blob value, optional DOMString filename);
void <a href="/en-US/docs/DOM/XMLHttpRequest/FormData#append()" title="DOM/XMLHttpRequest/FormData#append()">append</a>(DOMString name, DOMString value);</pre>
<h4 id="append()_Parameters" name="append()_Parameters">Parameters</h4>
<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_inline}} 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>
<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>7+</td>
        <td>{{CompatGeckoDesktop("2.0")}}</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>
    </tbody>
  </table>
</div>
<div id="compat-mobile">
  <table class="compat-table">
    <tbody>
      <tr>
        <th>Feature</th>
        <th>Android</th>
        <th>Chrome for 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>{{CompatUnknown}}</td>
        <td>{{CompatGeckoMobile("2.0")}}</td>
        <td>{{CompatUnknown}}</td>
        <td>
          <p>12+</p>
        </td>
        <td>{{CompatUnknown}}</td>
      </tr>
      <tr>
        <td>append with filename</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatGeckoDesktop("22.0")}}</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
        <td>{{CompatUnknown}}</td>
      </tr>
    </tbody>
  </table>
  <p>&nbsp;</p>
  <p><strong style="color: rgb(93, 86, 54); line-height: 21px; background-color: rgb(250, 249, 226);">Note:</strong><span style="color: rgb(93, 86, 54); line-height: 21px; background-color: rgb(250, 249, 226);">&nbsp;XHR in Android 4.0 sends empty content for FormData with blob</span><span style="color: rgb(93, 86, 54); line-height: 21px; background-color: rgb(250, 249, 226);">.</span></p>
</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 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-US/docs/DOM/XMLHttpRequest/Using_XMLHttpRequest" title="Using XMLHttpRequest">Using XMLHttpRequest</a></li>
  <li><a href="/en-US/docs/DOM/XMLHttpRequest/FormData/Using_FormData_Objects" title="DOM/XMLHttpRequest/FormData/Using_FormData_objects">Using FormData objects</a></li>
  <li>{{HTMLElement("Form")}}</li>
</ul>
Revert to this revision