Skip to content

feat(web_adapter): implement download method for web platforms#2485

Open
meylis1998 wants to merge 2 commits intocfug:mainfrom
meylis1998:feat/web-download-support
Open

feat(web_adapter): implement download method for web platforms#2485
meylis1998 wants to merge 2 commits intocfug:mainfrom
meylis1998:feat/web-download-support

Conversation

@meylis1998
Copy link

Summary

  • Implement the download() method for web platforms using the Blob API instead of throwing UnsupportedError
  • Add comprehensive tests for the new functionality
  • Update CHANGELOG

Details

This PR enables file downloads in web browsers using the same dio.download() API that works on native platforms.

How it works:

  1. Fetches file content as bytes with full progress tracking support
  2. Creates a Blob from the response bytes
  3. Triggers the browser's native download dialog via an anchor element click
  4. Uses savePath as the suggested filename (extracts filename portion from paths)

Supported features on web:

Feature Support
onReceiveProgress ✅ Full support
cancelToken ✅ During fetch phase
String savePath ✅ Used as suggested filename
Callback savePath ✅ Receives headers, returns filename
Custom headers/auth ✅ Full support

Limitations (documented in code):

  • deleteOnError parameter is ignored (not applicable on web)
  • fileAccessMode parameter is ignored (not applicable on web)
  • Entire file is loaded into memory before download triggers (not suitable for very large files)
  • Actual save location is determined by browser settings, not by savePath

Usage example:

// Works the same on web now!
await dio.download(
  'https://example.com/file.pdf',
  'my-file.pdf',  // Used as suggested filename
  onReceiveProgress: (received, total) {
    print('${(received / total * 100).toStringAsFixed(0)}%');
  },
);

Fixes #2408

Test plan

  • dart analyze passes with no issues
  • Added unit tests for argument validation
  • Added tests for String and callback savePath variants
  • Added tests for progress callback and cancellation support
  • Manual testing in browser environment

Implement the download() method for web platforms using the Blob API
instead of throwing UnsupportedError. This allows users to download
files in web browsers using the same API as native platforms.

The implementation:
- Fetches file content as bytes with progress tracking support
- Creates a Blob from response bytes
- Triggers browser's native download dialog via anchor element
- Uses savePath as suggested filename (extracts filename from path)
- Supports both String and callback-based savePath

Limitations on web (documented in code):
- deleteOnError and fileAccessMode parameters are ignored
- Entire file is loaded into memory (not suitable for very large files)
- Actual save location is determined by browser, not savePath

Fixes cfug#2408
@meylis1998 meylis1998 requested a review from a team as a code owner January 30, 2026 15:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Cannot download the file in the browser

1 participant