Content-Disposition
Description
The Content-Disposition response header indicates how the content of the response should be presented to the user. This header primarily serves two purposes:
-
In regular HTTP responses: It suggests whether the content should be displayed inline (i.e., within the browser window) or as an attachment (i.e., downloaded to the user's device).
-
In multipart bodies: It provides information about the field it applies to, including the field name and an optional filename for file uploads.
The Content-Disposition header is particularly useful when servers want to force browsers to download content rather than attempting to display it, or when they want to suggest a filename for the downloaded content.
Syntax
The syntax of the Content-Disposition header follows this structure:
<disposition-type>: Eitherinline(display in browser) orattachment(prompt for download).filename="<filename>": Optional parameter suggesting a filename for saving the content.filename*=<encoded-filename>: Optional parameter for filenames containing non-ASCII characters, using UTF-8 encoding and URL encoding.
Example Syntax
This example tells the browser to treat the content as a downloadable attachment with the suggested filename "report.pdf".
Examples
Basic Download Example
A response forcing the browser to download a PDF file:
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 20:00:00 GMT
Content-Type: application/pdf
Content-Length: 123456
Content-Disposition: attachment; filename="annual_report_2025.pdf"
[... PDF data ...]
In this example, the browser will prompt the user to save the file with the suggested name "annual_report_2025.pdf" rather than attempting to display it in the browser window.
Inline Display Example
A response suggesting inline display of content:
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 20:10:30 GMT
Content-Type: image/jpeg
Content-Length: 54321
Content-Disposition: inline; filename="profile_photo.jpg"
[... JPEG data ...]
This response suggests that the browser should display the image within the browser window rather than downloading it, but still provides a filename in case the user chooses to save it.
Non-ASCII Filename Example
A response with a filename containing non-ASCII characters:
HTTP/1.1 200 OK
Date: Mon, 02 Jun 2025 20:20:45 GMT
Content-Type: text/plain
Content-Length: 1234
Content-Disposition: attachment; filename="document.txt"; filename*=UTF-8''r%C3%A9sum%C3%A9.txt
[... Text data ...]
In this example, the server provides both a basic ASCII filename ("document.txt") and an encoded non-ASCII filename ("résumé.txt") using the filename* parameter. Browsers that support the extended format will use "résumé.txt" as the suggested filename.
Form Data Upload Example
In a multipart form data request, the Content-Disposition header is used to describe form fields:
POST /upload HTTP/1.1
Host: example.com
Content-Type: multipart/form-data; boundary=boundary123
--boundary123
Content-Disposition: form-data; name="field1"
value1
--boundary123
Content-Disposition: form-data; name="file1"; filename="example.txt"
Content-Type: text/plain
Content of the file.
--boundary123--
Summary
The Content-Disposition response header provides important instructions to browsers about how to handle the content they receive. By specifying whether content should be displayed inline or downloaded as an attachment, and by suggesting appropriate filenames, servers can control the user experience when delivering files. This header is essential for file download functionality in web applications and APIs, ensuring that content is presented to users in the most appropriate way and with meaningful filenames.