Content-Disposition header generator and checker

What the Content-Disposition header does

Content-Disposition is the response header that turns a page into a download and gives the saved file a name. It has one required part, the disposition type, and the parameters that matter here are filename and filename*. A type of attachment tells the browser to prompt for a save; inline tells it to behave normally, which is why inline is only useful once a filename is attached to it — otherwise it asks for exactly what happens with no header at all.

A third case is worth knowing because it is silent: RFC 6266 says unknown or unhandled disposition types should be handled the same way as attachment. So a typo like attachement does not fall back to displaying the file, it triggers a download. This tool reports that rather than passing over it, because a header that works by accident is one nobody looks at again.

The filename is advisory in the strongest sense. The specification tells recipients to be very careful with it: never trust folder information, keep only the last path segment, refuse to write anywhere the user did not sanction, and strip or replace control characters and leading and trailing whitespace. A browser that renamed your file was following the rules.

How to use it

1. Pick a mode. Build a header takes the filename you want a visitor to see and writes the header for it. Check a header takes one you already have — pasted with or without the field name — and works out what a recipient makes of it.
2. In build mode, type the name exactly as it should appear. Accents and all. Choose attachment or inline, and choose how the ASCII fallback spells an accented letter: the passport spelling turns ä into ae, or you can have the single letter a. Copy the header out with the button.
3. In check mode, read the two rows that matter. Filename used is the name a current browser actually saves, and Taken from says which of the two parameters supplied it. The findings below split into errors, which break something, warnings, which are valid but work against you, and notes, which are valid and simply do nothing.

Why a correct header sends the filename twice

This is the part that surprises people, and it is the whole reason the tool exists. RFC 6266 says the two parameters differ only in that filename* uses an encoding that allows characters outside ISO-8859-1 — and then, crucially, that when both are present in a single header field value, recipients should pick filename* and ignore filename. The advice is not to replace one with the other. It is to send both.

The reasoning is compatibility. The extended form arrived after a lot of software had already shipped, so a sender who uses only filename* leaves anything older with nothing to work from, while a sender who uses only filename is stuck inside a character set that cannot spell most of the world's names. Appendix D of the same document sets out the resolution in order: include filename when US-ASCII is expressive enough, add filename* where it is not, generate the fallback by substituting ASCII sequences, and put filename first, because some existing parsers stop at the first name they understand.

That substitution advice comes with its own worked example — the letter ä becomes ae — which is the passport spelling rather than the single-letter one, and that is what this tool uses by default. The table behind it is the same one the site's slug tool uses, taken from ICAO Doc 9303, and it exists because the obvious recipe is wrong: normalising and stripping accent marks quietly deletes about a dozen Latin letters outright rather than folding them, so Ærø becomes the single letter r and Straße loses its ß. Here Ærø.txt falls back to AEroe.txt.

Appendix D also admits the limit of its own advice, in one clause: this may not be possible in some locales. A name written entirely in Japanese or Arabic has no ASCII spelling at all, so this tool does not invent one. It writes a plain placeholder stem, keeps the extension, lists every character it could not spell, and says on the page that the fallback is a placeholder. Every current browser reads filename* and gets the real name regardless; only genuinely ancient software sees the placeholder.

The extended value is not encodeURIComponent

The encoding for filename* is defined by RFC 8187, and it is not URL encoding, although it looks close enough to fool almost everybody. The value is a character encoding name, two single quotes, and then a sequence in which every character is either percent-encoded or drawn from a set the specification calls attr-char — which it defines as the token characters except asterisk, apostrophe and percent.

Compare that set against encodeURIComponent, which is what nearly every code sample reaches for, and the two disagree in both directions. Swept across ASCII, encodeURIComponent leaves exactly four characters in place that attr-char forbids: the apostrophe, both parentheses, and the asterisk. It also escapes seven that attr-char permits, which is harmless, because a percent escape is always legal. The four are not harmless, and they are not exotic: report (final).pdf and O'Brien.pdf are ordinary filenames, and both of them come out of encodeURIComponent carrying a character the grammar does not allow.

There is a second trap in the same place. RFC 8187 removed the requirement to support ISO-8859-1 in its 2017 revision and now says producers must use UTF-8, so a value that announces a different character encoding is behind the specification even where it still works. And the extended value must never be quoted — the same document notes that a parser assembled from generic parts might well accept the quoted form anyway, which is exactly how a mistake like that survives testing.

What this will not tell you

This checks the text you paste and nothing else. A browser cannot fetch your server's headers for you, so the tool has no idea whether the header you are looking at is the one being sent, whether the file behind it exists, or whether its media type matches the extension. A header can be flawless and still describe the wrong response.

It also says nothing about whether the name is legal once it lands on disk. Reserved device names, the characters Windows forbids, and length limits are a separate rule set with a separate answer, and this site has a filename sanitizer for that question. The two problems look alike and share nothing: this one is about surviving the header, that one is about surviving the filesystem.

One deliberate omission: parameter continuations, the RFC 2231 mechanism that splits a long value across filename*0* and filename*1*. RFC 8187 states that continuations are not needed for HTTP header fields and does not adopt them, so a header using them is outside what this parses. If you have one, it came from software following an older MIME convention in a place that never called for it.

Finally, none of this makes a filename authoritative. The specification is emphatic that a recipient treats it as advice, may substitute a name that means something special to the filesystem, and must ensure any extension it trusts is a safe one. What a correct header buys you is the best chance of the name you meant, not a guarantee of it.

Why is it free?

Building and parsing a header is text work, and it runs in your browser. There is no server in the loop, so there is nothing to bill for and no account to create.

Nothing is uploaded and nothing is stored. Reload the page and it has forgotten your filename.