Revision 1086575 of Content-Disposition

  • Revision slug: Web/HTTP/Headers/Content-Disposition
  • Revision title: Content-Disposition
  • Revision id: 1086575
  • Created:
  • Creator: fscholz
  • Is current revision? No
  • Comment review; the thing is called content-dispositionWeb/HTTP/Headers/Cache-Disposition Web/HTTP/Headers/Content-Disposition

Revision Content

{{HTTPSidebar}}

In a multipart/form-data body, the HTTP Content-Disposition general header is a header that can be used on the subpart of a multipart body to give information about the field it applies to. The subpart is delimited by the boundary defined in the {{HTTPHeader("Content-Type")}} header. Used on the body itself, Content-Disposition has no effect.

The Content-Disposition header is defined in the larger context of MIME messages for e-mail, but only a subset of the possible parameters apply to HTTP forms and {{HTTPMethod("POST")}} requests. Only the value form-data, as well as the optional parameter name and filename, can be used in the HTTP context.

Header type {{Glossary("General header")}} (for subpart of a multipart body)
{{Glossary("Forbidden header name")}} no

Syntax

The first parameter in the HTTP context is always form-data; additional parameters are case-insensitive and have arguments, that use quoted-string syntax after the '=' sign. Multiple parameters are separated by a semi-colon (';').

Content-Disposition: form-data
Content-Disposition: form-data; name="fieldName"
Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"

Parameters

name
Is followed by a string containing the name of the HTML field in the form that the content of this subpart refer to. When dealing with multiple files in the same field (for example, the {{htmlattrxref("multiple", "input")}} attribute of an {{HTMLElement("input","<input type=file>")}} element, there can be several subparts with the same name.
A name with a value of '_charset_' indicates that the part is not an HTML field, but the default charset to use for parts without explicit charset information.
filename
Is followed by a string containing the original name of the file transmitted in the subpart. The filename is always optional and must not be used blindly by the application: path information should be striped, and conversion to the server file system rules should be done. This parameter provides mostly indicative information.

Examples

POST /test.html HTTP/1.1
Host: example.org
Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data; name="field1"

value1
--boundary
Content-Disposition: form-data; name="field2"; filename="example.txt"

value2

Specifications

Specification Title
{{RFC("7578")}} Returning Values from Forms: multipart/form-data
{{RFC("2183")}} Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field

Browser compatibility

{{Compat}}

See also

  • HTML Forms
  • The {{HTTPHeader("Content-Type")}} defining the boundary of the multipart body.
  • The {{domxref("FormData")}} interface used to manipulate form data for use in the {{domxref("XMLHttpRequest")}} API.

Revision Source

<div>{{HTTPSidebar}}</div>

<p>In a <code>multipart/form-data</code> body, the HTTP <strong><code>Content-Disposition</code></strong> general header is a header that can be used on the subpart of a multipart body to give information about the field it applies to. The subpart is delimited by the <em>boundary</em> defined in the {{HTTPHeader("Content-Type")}} header. Used on the body itself, <code>Content-Disposition</code> has no effect.</p>

<p>The <code>Content-Disposition</code> header is defined in the larger context of MIME messages for e-mail, but only a subset of the possible parameters apply to HTTP forms and {{HTTPMethod("POST")}} requests. Only the value <code>form-data</code>, as well as the optional parameter <code>name</code> and <code>filename</code>, can be used in the HTTP context.</p>

<table class="properties">
 <tbody>
  <tr>
   <th scope="row">Header type</th>
   <td>{{Glossary("General header")}} (for subpart of a multipart body)</td>
  </tr>
  <tr>
   <th scope="row">{{Glossary("Forbidden header name")}}</th>
   <td>no</td>
  </tr>
 </tbody>
</table>

<h2 id="Syntax">Syntax</h2>

<p>The first parameter in the HTTP context is always <code>form-data</code>; additional parameters are case-insensitive and have arguments, that use quoted-string syntax after the <code>'='</code> sign. Multiple parameters are separated by a semi-colon (<code>';'</code>).</p>

<pre class="syntaxbox">
Content-Disposition: form-data
Content-Disposition: form-data; name="fieldName"
Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"</pre>

<h3 id="Parameters">Parameters</h3>

<dl>
 <dt><code>name</code></dt>
 <dd>Is followed by a string containing the name of the HTML field in the form that the content of this subpart refer to. When dealing with multiple files in the same field (for example, the {{htmlattrxref("multiple", "input")}} attribute of an <code>{{HTMLElement("input","&lt;input type=file&gt;")}}</code> element, there can be several subparts with the same name.<br />
 A <code>name</code> with a value of <code>'_charset_'</code> indicates that the part is not an HTML field, but the default charset to use for parts without explicit charset information.</dd>
 <dt><code>filename</code></dt>
 <dd>Is followed by a string containing the original name of the file transmitted in the subpart. The filename is always optional and must not be used blindly by the application: path information should be striped, and conversion to the server file system rules should be done. This parameter provides mostly indicative information.</dd>
</dl>

<h2 id="Examples">Examples</h2>

<pre>
POST /test.html HTTP/1.1
Host: example.org
Content-Type: multipart/form-data;boundary="boundary"

--boundary
Content-Disposition: form-data; name="field1"

value1
--boundary
Content-Disposition: form-data; name="field2"; filename="example.txt"

value2</pre>

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

<table class="standard-table">
 <tbody>
  <tr>
   <th scope="col">Specification</th>
   <th scope="col">Title</th>
  </tr>
  <tr>
   <td>{{RFC("7578")}}</td>
   <td>Returning Values from Forms: multipart/form-data</td>
  </tr>
  <tr>
   <td>{{RFC("2183")}}</td>
   <td>Communicating Presentation Information in Internet Messages: The Content-Disposition Header Field</td>
  </tr>
 </tbody>
</table>

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

<p class="hidden">To contribute to this compatibility data, please write a pull request against this file: <a href="https://github.com/mdn/browser-compat-data/blob/master/http/headers.json">https://github.com/mdn/browser-compat-data/blob/master/http/headers.json</a>.</p>

<p>{{Compat}}</p>

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

<ul>
 <li><a href="/en-US/docs/Web/Guide/HTML/Forms">HTML Forms</a></li>
 <li>The {{HTTPHeader("Content-Type")}} defining the boundary of the multipart body.</li>
 <li>The {{domxref("FormData")}} interface used to manipulate form data for use in the {{domxref("XMLHttpRequest")}} API.</li>
</ul>
Revert to this revision