Add-ons

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).

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.

Browser compatibility

ChromeEdgeFirefoxFirefox for AndroidOpera
Basic support Yes No4748 Yes
body Yes No5252 Yes
conflictAction Yes No4748 Yes
filename Yes No4748 Yes
headers Yes No4748 Yes
incognito No No5757 No
method Yes No471481 Yes
saveAs Yes No522522 Yes

1. POST is supported from version 52.

2. Before version 58, if this option was omitted, Firefox would never show the file chooser, regardless of the value of the browser's preference.

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

 Contributors to this page: wbamberg, lgreco, CaemU, Makyen, chrisdavidmills, aswan
 Last updated by: wbamberg,