The HTTPContent-Disposition header indicates whether content should be displayedinline in the browser as a web page or part of a web page or downloaded as anattachment locally.

In a multipart body, the header must be used on each subpart to provide information about its corresponding field. The subpart is delimited by theboundary defined in theContent-Type header. When used on the body itself,Content-Disposition has no effect.

TheContent-Disposition header is defined in the larger context of MIME messages for email, but only a subset of the possible parameters apply to HTTP forms andPOST requests. Only the valueform-data, as well as the optional directivename andfilename, can be used in the HTTP context.

Syntax

As a response header for the main body

The first parameter in the HTTP context is eitherinline (default value, indicating it can be displayed inside the Web page, or as the Web page) orattachment (indicating it should be downloaded; most browsers presenting a 'Save as' dialog, prefilled with the value of thefilename parameters if present).

Content-Disposition: inlineContent-Disposition: attachmentContent-Disposition: attachment; filename="file name.jpg"Content-Disposition: attachment; filename*=UTF-8''file%20name.jpg

The quotes around the file name are optional, but are necessary if you use special characters in the file name, such as spaces.

The parametersfilename andfilename* differ only in thatfilename* uses the encoding defined inRFC 5987, section 3.2.When bothfilename andfilename* are present in a single header field value,filename* is preferred overfilename when both are understood. It's recommended to include both for maximum compatibility, and you can convertfilename* tofilename by substituting non-ASCII characters with ASCII equivalents (such as convertingé toe).You may want to avoid percent escape sequences infilename, because they are handled inconsistently across browsers. (Firefox and Chrome decode them, while Safari does not.)

Browsers may apply transformations to conform to the file system requirements, such as converting path separators (/ and\) to underscores (_).

As a header for a multipart body

Amultipart/form-data body requires aContent-Disposition header to provide information about each subpart of the form (e.g., for every form field and any files that are part of field data).The first directive is alwaysform-data, and the header must also include aname parameter to identify the relevant field. Additional directives are case-insensitive.The value of any arguments (after the= sign) may be a either token or a quoted string.Quoted strings are recommended, and many server implementations require the values to be quoted.This is because a token must be US-ASCII for MIME type headers likeContent-Disposition, and US-ASCII does not allow some characters that are common in filenames and other values.Multiple parameters are separated by a semicolon (;).

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

Directives

name

Is followed by a string containing the name of the HTML field in the form that the content of this subpart refers to. When dealing with multiple files in the same field (for example, themultiple attribute of an<input type="file"> element), there can be several subparts with the same name.

Aname 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. This parameter provides mostly indicative information. The suggestions inRFC2183 apply:

• Prefer ASCII characters if possible (the client may percent-encode it, as long as the server implementation decodes it).
• Any path information should be stripped, such as by replacing/ with_.
• When writing to disk, it should not overwrite an existing file.
• Avoid creating special files with security implications, such as creating a file on the command search path.
• Satisfy other file system requirements, such as restricted characters and length limits.

Note that the request header does not have thefilename* parameter and does not allow RFC 5987 encoding.

Examples

Triggering download prompt for a resource

The following response triggers the "Save As" dialog in a browser:

200 OKContent-Type: text/html; charset=utf-8Content-Disposition: attachment; filename="cool.html"Content-Length: 21<HTML>Save me!</HTML>

The HTML file will be downloaded rather than displayed in the browser.Most browsers will prompt users to save it with thecool.html file name by default (as specified in thefilename directive).

HTML posting multipart/form-data content type

The following example shows an HTML form sent usingmultipart/form-data using theContent-Disposition header.In practice, the boundary valuedelimiter123 would be a browser-generated string like----8721656041911415653955004498:

POST /test.html HTTP/1.1Host: example.orgContent-Type: multipart/form-data;boundary="delimiter123"--delimiter123Content-Disposition: form-data; name="field1"value1--delimiter123Content-Disposition: form-data; name="field2"; filename="example.txt"value2--delimiter123--

Specifications

Browser compatibility

See also

• HTML Forms
• TheContent-Type defining the boundary of the multipart body.
• TheFormData interface used to prepare form data for use in thefetch() orXMLHttpRequest APIs.