downloads.download()

The download() function of the downloads API downloads a file, given its URL and other optional preferences.

  • If the specified url uses the HTTP or HTTPS protocol, then the request will include all cookies currently set for its hostname.
  • If both filename and saveAs are specified, then the Save As dialog will be displayed, pre-populated with the specified filename.

This is an asynchronous function that returns a Promise.

Syntax

var downloading = browser.downloads.download(
  options                   // object
)

Parameters

options
An object specifying what file you wish to download, and any other preferences you wish to set concerning the download. It can contain the following properties:
bodyOptional
A string representing the post body of the request.
conflictActionOptional
A string representing the action you want taken if there is a filename conflict, as defined in the downloads.FilenameConflictAction type (defaults to "uniquify" when it is not specified).
filenameOptional
A string representing a file path relative to the default downloads directory — this provides the location where you want the file to be saved, and what filename you want to use. Absolute paths, empty paths, and paths containing back-references (../) will cause an error. If omitted, this value will default to the filename already given to the download file, and a location immediately inside the downloads directory.
headersOptional
An array of objects representing extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol. Each header is represented as a dictionary object containing the keys name and either value or binaryValue, restricted to those allowed by XMLHttpRequest.
incognitoOptional
A boolean: if present and set to true, then associate this download with a private browsing session. This means that it will only appear in the download manager for any private windows that are currently open.
methodOptional
A string representing the HTTP method to use if the url uses the HTTP[S] protocol. This may be either "GET" or "POST".
saveAsOptional

A boolean that specifies whether to provide a file chooser dialog to allow the user to select a filename (true), or not (false).

If this option is omitted, the browser will show the file chooser or not based on the general user preference for this behavior (in Firefox this preference is labeled "Always ask you where to save files" in about:preferences, or browser.download.useDownloadDir in about:config).

Note: Firefox for Android raises an error if saveAs is set to true. The parameter is ignored when saveAs is false or not included.

url
A string representing the URL to download.

Return value

A Promise. If the download started successfully, the promise will be fulfilled with the id of the new downloads.DownloadItem. Otherwise the promise will be rejected with an error message.

If you use URL.createObjectURL() to download data created in JavaScript and you want to revoke the object URL (with revokeObjectURL) later (as it is strongly recommend), you need to do that after the download has been completed. To do so, listen to the downloads.onChanged event.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxOperaFirefox for Android
Basic supportChrome Full support YesEdge No support NoFirefox Full support 47Opera Full support YesFirefox Android Full support 48
bodyChrome Full support YesEdge No support NoFirefox Full support 52Opera Full support YesFirefox Android Full support 52
conflictActionChrome Full support YesEdge No support NoFirefox Full support 47Opera Full support YesFirefox Android Full support 48
filenameChrome Full support YesEdge No support NoFirefox Full support 47Opera Full support YesFirefox Android Full support 48
headersChrome Full support YesEdge No support NoFirefox Full support 47Opera Full support YesFirefox Android Full support 48
incognitoChrome No support NoEdge No support NoFirefox Full support 57Opera No support NoFirefox Android Full support 57
methodChrome Full support YesEdge No support NoFirefox Full support 47
Notes
Full support 47
Notes
Notes POST is supported from version 52.
Opera Full support YesFirefox Android Full support 48
Notes
Full support 48
Notes
Notes POST is supported from version 52.
saveAsChrome Full support YesEdge No support NoFirefox Full support 52
Notes
Full support 52
Notes
Notes Before version 58, if this option was omitted, Firefox would never show the file chooser, regardless of the value of the browser's preference.
Opera Full support YesFirefox Android Full support 52
Notes
Full support 52
Notes
Notes Before version 58, if this option was omitted, Firefox would never show the file chooser, regardless of the value of the browser's preference.

Legend

Full support  
Full support
No support  
No support
See implementation notes.
See implementation notes.

Examples

The following snippet attempts to download an example file, also specifying a filename and location to save it in, and the uniquify conflictAction option.

function onStartedDownload(id) {
  console.log(`Started downloading: ${id}`);
}

function onFailed(error) {
  console.log(`Download failed: ${error}`);
}

var downloadUrl = "https://example.org/image.png";

var downloading = browser.downloads.download({
  url : downloadUrl,
  filename : 'my-image-again.png',
  conflictAction : 'uniquify'
});

downloading.then(onStartedDownload, onFailed);

Acknowledgements

This API is based on Chromium's chrome.downloads API.

Document Tags and Contributors

Last updated by: irenesmith,