HTTP Headers
Content Disposition
The HTTP Content-Disposition
header specifies whether content should be displayed inline in the browser as a web page or be downloaded as an attachment to be saved locally.
In a multipart message body, this header must be included in each subpart to provide relevant information about that particular section. The subparts are separated by the boundary that is defined in the Content-Type
header. When applied directly to the message body, Content-Disposition
has no effect.
The Content-Disposition
header originates from the MIME standard used for email messages. However, in the context of HTTP forms and POST
requests, only a subset of its parameters are applicable. These include the value form-data
, along with optional directives such as name
and filename
, which are used to specify form field names and associated filenames respectively.
It is important to note that the Content-Disposition
header is not a forbidden request header, and thus can be used in requests where appropriate.
Syntax
As a response header for the main body
The first parameter in the HTTP context is either inline
(default, indicating it can be displayed inside the web page) or attachment
(indicating it should be downloaded; most browsers present a ‘Save as’ dialog, prefilled with the value of the filename
parameter if present).
Content-Disposition: inline
Content-Disposition: attachment
Content-Disposition: attachment; filename="file name.jpg"
Content-Disposition: attachment; filename*=UTF-8''file%20name.jpg
The quotes around the file name are optional but necessary if you use special characters, such as spaces, in the file name.
The parameters filename
and filename*
differ primarily in encoding: filename*
uses the encoding specified in RFC 5987, section 3.2. When both are present, filename*
is preferred, but including both enhances compatibility. To ensure maximum compatibility, you can convert filename*
to filename
by replacing non-ASCII characters with ASCII equivalents (e.g., converting é
to e
). Avoid percent escape sequences in filename
as browsers handle them inconsistently: Firefox and Chrome decode them, Safari does not.
Browsers may modify filenames to meet filesystem constraints, such as replacing path separators (/
and \
) with underscores (_
).
Note: Chrome and Firefox 82+ prioritize the <a>
element’s download
attribute over the Content-Disposition: inline
header for same-origin URLs. Earlier Firefox versions depend on the header and will display the content inline.
As a header for a multipart body
A multipart/form-data
body requires a Content-Disposition
header describing each subpart, such as form fields and files. The first directive is always form-data
. The header must include a name
parameter identifying the form field. Additional directives are case-insensitive and use quoted-string syntax after an equal sign, separated by semicolons.
Content-Disposition: form-data; name="fieldName"
Content-Disposition: form-data; name="fieldName"; filename="filename.jpg"
Directives
name
- Contains the name of the HTML form field associated with this part. In cases of multiple files in the same field (using the multiple attribute in
<input type="file">
), several subparts may have the same name.A
name
value of'_charset_'
indicates that this part specifies the default charset to be used when no charset info is provided.
filename
- Contains the original filename transmitted. This parameter offers mainly informational purposes. The guidelines from RFC2183 suggest:
- Use ASCII characters where possible (percent-encoding optional as the server decodes it).
- Strip any path info, replacing path separators (
/
) with underscores (_
).
- Strip any path info, replacing path separators (
- Ensure filename does not overwrite existing files when saving.
- Avoid creating files with security implications, such as files on the command search path.
- Satisfy filesystem constraints, including character restrictions and length limits.
Note that request headers do not support the filename*
parameter or RFC 5987 encoding.
Example
Triggering download prompt for a resource
The following response prompts the browser to display a ‘Save As’ dialog:
200 OK
Content-Type: text/html; charset=utf-8
Content-Disposition: attachment; filename="cool.html"
Content-Length: 21
<HTML>Save me!</HTML>
The HTML file will be downloaded instead of displayed in the browser.
Most browsers will suggest saving it as cool.html
, as specified in the filename
directive.
HTML posting multipart/form-data content type
The example below illustrates an HTML form submitted via multipart/form-data
with the Content-Disposition
header.
Typically, the boundary value delimiter123
is generated by browsers, such as ----8721656041911415653955004498
:
POST /test.html HTTP/1.1
Host: example.org
Content-Type: multipart/form-data; boundary="delimiter123"
--delimiter123
Content-Disposition: form-data; name="field1"
value1
--delimiter123
Content-Disposition: form-data; name="field2"; filename="example.txt"
value2
--delimiter123--
How to Modify Header using Requestly
Requestly is a powerful Chrome extension that allows you to modify HTTP headers, including the Content-Disposition header. This is especially helpful for controlling how downloaded files are handled by the browser or testing file download behaviors during development. Steps to Modify the Content-Disposition Header:
- Install and open the Requestly Chrome extension. You can find it on the Chrome Web Store.
- Create a new rule: Click on “Create Rule” and choose “Modify Headers” from the list of available rule types.
- Add a new header modification:
- Under “Action”, select “Add” or “Override”.
- In the “Header Name” field, enter Content-Disposition.
- In the “Header Value” field, enter your desired value (e.g., attachment; filename=”example.txt”).
- Set the URL condition: Specify the URL or pattern where this header change should apply (e.g., https://your-download-server.com/*).
- Save the rule.
Once configured, Requestly will inject the specified Content-Disposition header into all matching responses, letting you control file download prompts or inline display behavior during testing.
Modifying the Content-Disposition header is useful when you want to test how files are downloaded or displayed in the browser. For example, you can force a file to download with a specific name or display inline, helping you ensure your server’s file delivery is working as expected.
Table of Contents
- No headings found.