How to implement Content-Disposition: attachment?

How to implement Content-Disposition: attachment?

  1. Blog
  2. 15 November 2026
  3. 3 min read

Stefan Bogdanescu

Founder & Senior Architect

Where Content-Disposition Lives: Server-Side Headers, Not HTML

You cannot force a browser to download a file simply by tweaking your HTML markup. The HTTP response headers determine how the user agent handles the payload, and specifically, the Content-Disposition header is where this logic resides. Your current anchor tag points to a valid resource, but without the correct server configuration, most modern browsers will treat audio files as inline content that can be played directly within the <audio> element or an embedded player, rather than triggering a download.

To achieve the behavior you want—where a left-click triggers a download—you must configure your web server to send the Content-Disposition: attachment header with every request for that specific MP3 file. This is strictly a server-side configuration task, not something achieved through HTML attributes or CSS classes.

Implementing Header Configuration

The approach depends entirely on the software powering your web server. Below are the standard implementations for common environments.

Apache

If you are running Apache, you can handle this at the virtual host level or via a .htaccess file within your project directory. You need to map specific file extensions to the attachment disposition.

<FilesMatch "\.(mp3|ogg|wav)$">
    Header set Content-Disposition "attachment"
</FilesMatch>

Alternatively, you can apply this globally by using AddType directives combined with Header, though mapping by extension is often cleaner for specific asset folders. Ensure your mod_headers module is enabled; otherwise, the server will ignore these instructions.

Nginx

In an Nginx environment, you configure this within the location block that serves your static assets. You can target a specific file or a directory of files.

location /MP3/ {
    default_type audio/mpeg;
    add_header Content-Disposition "attachment";
}

Be aware that using add_header in Nginx may append the header to existing ones rather than replacing them if not configured carefully, though for static files it typically overrides previous content headers. It is crucial to ensure you are not inadvertently stripping this header when passing requests through a reverse proxy like Varnish or Cloudflare unless explicitly preserved.

PHP Applications (Laravel)

If your site is built on Laravel and you are serving these files via the framework rather than static file storage, the logic must be injected into the controller action. When returning a response that includes an MP3 file, use the response() helper to set the header before sending it.

use Illuminate\Http\Response;

public function download($filename)
{
    $path = public_path('MP3/' . $filename);
    
    if (!file_exists($path)) {
        abort(404);
    }

    return response()->make(
        file_get_contents($path),
        200,
        [
            'Content-Type' => 'audio/mpeg',
            'Content-Disposition' => 'attachment; filename="' . basename($filename) . '"',
        ]
    );
}

Using Laravel's response() method ensures the headers are correctly prioritized. Note that setting the header here is specific to routes handled by this controller. If you are serving static files directly from the filesystem without passing through PHP logic, the .htaccess or Nginx approach remains necessary.

Trade-offs and Browser Behavior

Setting Content-Disposition: attachment effectively removes the browser's ability to play the media inline. This is a functional trade-off: you gain automatic download behavior but lose the convenience of an embedded audio player for previewing tracks. Users will no longer hear the music before downloading it; they must trust that the file works or check it after the download completes.

Furthermore, while this forces a download dialog on most desktop browsers, mobile Safari and some mobile Chrome versions often ignore Content-Disposition headers in favor of their own heuristics, potentially still attempting to play the audio if supported by the device. If universal playback prevention is required alongside forced downloads, you may need to serve the file with a specific MIME type that your target devices handle differently, though this reduces compatibility across the board.

Conclusion on Implementation

The solution lies entirely in your server configuration or application controller logic, not your HTML markup. By adjusting the headers at the source, you ensure consistent behavior regardless of how the user interacts with the link.

Our network