Revision 1095933 of Content-Disposition

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

<div>In a regular HTTP response, the <code><strong>Content-Disposition</strong></code> response header is a header indicating if the content is expected to be displayed <em>inline</em> in the browser, that is, as a Web page or as part of a Web page, or as an <em>attachment</em>, that is downloaded and saved locally.</div>

<div>&nbsp;</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 directive <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("Response header")}} (for the main body)<br />
    {{Glossary("General header")}} (for a 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>

<h3 id="As_a_response_header_for_the_main_body">As a response header for the main body</h3>

<p>The first parameter in the HTTP context is either <code>inline</code> (default value, indicating it can be display inside the Web page, or as the Web page) or <code>attachment</code> (indicating it should be downloaded; most browsers presenting a 'Save as' dialog, prefilled with the value of the <code>filename</code> parameters if present</p>

<pre class="syntaxbox">
Content-Disposition: inline
Content-Disposition: attachment
Content-Disposition: attachment; filename="filename.jpg"</pre>

<h3 id="As_a_header_for_a_multipart_body">As a header for a multipart body</h3>

<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="Directives">Directives</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. 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. When used in combination with <code>Content-Disposition: attachment</code>, it is used a the default filename for an eventual 'Save As" dialog presented to the user.</dd>
</dl>

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

<p>A response triggering the "Save As" dialog:</p>

<pre>
200 OK
Content-Type: text/html; charset=utf-8
Content-Disposition: attachment; filename="cool.html"
Content-Length: 22

&lt;HTML&gt;Save me!&lt;/HTML&gt;

</pre>

<p>This simple HTML file will be saved as a regular download rather than displayed in the browser. Most browsers will propose to save it under the <code>cool.html</code> filename (by default).</p>

<p>An example of HTML form, posted using the <code>multipart/form-data</code> format that makes use of the <code>Content-Disposition</code> header:</p>

<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
--boundary--</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("6266")}}</td>
   <td>Use of the Content-Disposition Header Field in the Hypertext Transfer Protocol (HTTP)</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">The compatibility table in this page is generated from structured data. If you’d like to contribute to the data, please check out <a href="https://github.com/mdn/browser-compat-data/README.md">https://github.com/mdn/browser-compat-data/README.md</a> and send us a pull request.</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>