recursal/MDN huggingface dataset:
downloads.show()
================

The **`show()`** function of the `downloads` API shows the downloaded file in its containing folder in the underlying platform's file manager.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let showing = browser.downloads.show(
  downloadId             // integer
)
```

### Parameters

`downloadId`

An `integer` representing the ID of the `DownloadItem` to show.

### Return value

A `Promise`. If the request succeeds, the promise will be fulfilled with a boolean about whether the request was successful. If the request fails, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This example shows the most recently downloaded item:


```js
function onShowing(success) {
  console.log(`Showing download item: ${success}`);
}

function onError(error) {
  console.log(`Error opening item: ${error}`);
}

function openDownload(downloadItems) {
  if (downloadItems.length > 0) {
    latestDownloadId = downloadItems[0].id;
    let showing = browser.downloads.show(latestDownloadId);
    showing.then(onShowing, onError);
  }
}

let searching = browser.downloads.search({
  limit: 1,
  orderBy: ["-startTime"],
});

searching.then(openDownload, onError);
```


**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.DoubleDelta
=====================

The `DoubleDelta` type of the `downloads` API represents the difference between two doubles.

Type
----

Values of this type are objects. They contain the following properties:

`current` Optional

A `number` representing the current double value.

`previous` Optional

A `number` representing the previous double value.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.pause()
=================

The **`pause()`** function of the `downloads` API pauses a download.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let pausing = browser.downloads.pause(
  downloadId      // integer
)
```

### Parameters

`downloadId`

An `integer` representing the `id` of the download to pause.

### Return value

A `Promise`. If the call was successful, the download will be put in a paused state, and the promise will be fulfilled with no arguments. If the call fails, the promise will be rejected with an error message. The call will fail if the download is not active: for example, because it has finished downloading.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
function onPaused() {
  console.log(`Paused download`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let pausing = browser.downloads.pause(downloadId);
pausing.then(onPaused, onError);
```


**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.acceptDanger()
========================

The **`acceptDanger()`** function of the `downloads` API prompts the user to either accept or cancel a potentially dangerous download.

This function can't be called from background scripts, only in scripts that are running in a visible window (such as a browser or page action's popup).

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let prompting = browser.downloads.acceptDanger(
  downloadId      // integer
)
```

### Parameters

`downloadId`

An `integer` representing the `id` of the `DownloadItem` in question.

### Return value

A `Promise`. When the dialog closes, the promise will be fulfilled with no arguments.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.showDefaultFolder()
=============================

The **`showDefaultFolder()`** function of the `downloads` API opens the default downloads folder in the platform's file manager.

Syntax
------


```js
browser.downloads.showDefaultFolder();
```

### Parameters

None.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

The following snippet contains a show button, which when clicked invokes `showDefaultFolder()` to open the default downloads folder in the platform's file manager:


```js
let showBtn = document.querySelector(".show");

showBtn.onclick = () => {
  browser.downloads.showDefaultFolder();
};
```


**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.removeFile()
======================

The **`removeFile()`** function of the `downloads` API removes a downloaded file from disk.

This API removes the file from disk, but does not remove it from the browser's downloads history, therefore a call to `downloads.search()` will still return the item as a `DownloadItem`, but its `exists` attribute will be `false`.

To remove a file from the downloads history, you need to use `downloads.erase()`.

This is an asynchronous function that returns a `Promise`.

**Note:** If you want to remove a downloaded file from disk *and* erase it from history, you have to call `removeFile()` before you call `downloads.erase()`. If you try it the other way around you'll get an error when calling `removeFile()`, because the browser will no longer have a record of the download.

Syntax
------


```js
let removing = browser.downloads.removeFile(
  downloadId      // integer
)
```

### Parameters

`downloadId`

An `integer` representing the id of the `DownloadItem` you want to delete from disk.

### Return value

A `Promise`. If the request was successful, the promise will be fulfilled with no arguments. If the request failed, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Remove the most recently downloaded file:


```js
function onRemoved() {
  console.log(`Removed item`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

function remove(downloadItems) {
  if (downloadItems.length > 0) {
    let removing = browser.downloads.removeFile(downloadItems[0].id);
    removing.then(onRemoved, onError);
  }
}

let searching = browser.downloads.search({
  limit: 1,
  orderBy: ["-startTime"],
});

searching.then(remove, onError);
```

### Example extensions

* latest-download

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.StringDelta
=====================

The `StringDelta` type of the `downloads` API represents the difference between two strings.

Type
----

Values of this type are objects. They contain the following properties:

`current` Optional

A `string` representing the current string value.

`previous` Optional

A `string` representing the previous string value.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.onCreated
===================

The **`onCreated()`** event of the `downloads` API fires when a download begins, i.e. when `downloads.download()` is successfully invoked.

The listener is passed the `downloads.DownloadItem` object in question as a parameter.

Syntax
------


```js
browser.downloads.onCreated.addListener(listener)
browser.downloads.onCreated.removeListener(listener)
browser.downloads.onCreated.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether a given `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`function`

The function called when this event occurs. This function is passed this argument:

`downloadItem`

The `downloads.DownloadItem` object in question.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Log the URL of items as they are downloaded:


```js
function handleCreated(item) {
  console.log(item.url);
}

browser.downloads.onCreated.addListener(handleCreated);
```


**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.cancel()
==================

The **`cancel()`** function of the `downloads` API cancels a download. The call will fail if the download is not active: for example, because it has completed downloading.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let canceling = browser.downloads.cancel(
  downloadId      // integer
)
```

### Parameters

`downloadId`

`integer`. The id of the download to cancel.

### Return value

A `Promise`. If the request was successful, the promise will be fulfilled with no arguments. If the request failed, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
let downloadId = 13;

function onCanceled() {
  console.log(`Canceled download`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let canceling = browser.downloads.cancel(downloadId);
canceling.then(onCanceled, onError);
```


**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.setShelfEnabled()
===========================

The **`setShelfEnabled()`** function of the `downloads` API enables or disables the gray shelf at the bottom of every window associated with the current browser profile. The shelf will be disabled as long as at least one extension has disabled it.

If you try to enable the shelf when at least one other extension has already disabled it, the call will fail and `runtime.lastError` will be set with an appropriate error message.

**Note:** To use this function in your extension you must ask for the `"downloads.shelf"` manifest permission, as well as the `"downloads"` permission.

Syntax
------


```js
chrome.downloads.setShelfEnabled(enabled);
```


This API is also available as `browser.downloads.setShelfEnabled()`.

### Parameters

`enabled`

A `boolean` representing the state that you want to set `setShelfEnabled()` to — `true` for enable, and `false` for disable.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.erase()
=================

The **`erase()`** function of the `downloads` API erases matching `DownloadItems` from the browser's download history, without deleting the downloaded files from disk.

To remove the files from disk, you need to use `downloads.removeFile()`.

This is an asynchronous function that returns a `Promise`.

**Note:** If you want to remove a downloaded file from disk *and* erase it from history, you have to call `downloads.removeFile()` before you call `erase()`. If you try it the other way around you'll get an error when calling `downloads.removeFile()`, because it no longer exists according to the browser.

Syntax
------


```js
let erasing = browser.downloads.erase(
  query                    // DownloadQuery
)
```

### Parameters

`query`

A `downloads.DownloadQuery` object.

### Return value

A `Promise`. If the call was successful, the promise will be fulfilled with an array of integers representing the ids of the erased `DownloadItems`. If no items matching the query parameter could be found, the array will be empty. If the call failed, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Erase the most recent download:


```js
function onErased(ids) {
  console.log(`Erased: ${ids}`);
}

function onError(error) {
  console.log(`Error erasing item: ${error}`);
}

let erasing = browser.downloads.erase({
  limit: 1,
  orderBy: ["-startTime"],
});

erasing.then(onErased, onError);
```


Erase everything:


```js
function onErased(ids) {
  console.log(`Erased: ${ids}`);
}

function onError(error) {
  console.log(`Error erasing item: ${error}`);
}

let erasing = browser.downloads.erase({});
erasing.then(onErased, onError);
```

### Example extensions

* latest-download

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.getFileIcon()
=======================

The **`getFileIcon()`** function of the `downloads` API retrieves an icon for the specified download.

For new downloads, file icons are available after the `downloads.onCreated` event has been received. The image returned by this function while a download is in progress may be different from the image returned after the download is complete.

Icon retrieval is done by querying the underlying platform. The icon that is returned will therefore depend on a number of factors including state of the download, platform, registered file types and visual theme.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let gettingIcon = browser.downloads.getFileIcon(
  downloadId,           // integer
  options               // optional object
)
```

### Parameters

`downloadId`

An `integer` representing the ID of the download.

`options` Optional

An options `object` representing preferences for the icon to be retrieved. It can take the following properties:

`size` Optional

An `integer` representing the size of the icon. The returned icon's size will be the provided size squared (in pixels). If omitted, the default size for the icon is 32x32 pixels.


### Return value

A `Promise`. If the request succeeds, the promise will be fulfilled with a string representing the absolute URL of the icon. If the request fails, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

This example logs the icon URL for the most recent download:


```js
function gotIcon(iconUrl) {
  console.log(iconUrl);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

function getIcon(downloadItems) {
  if (downloadItems.length > 0) {
    latestDownloadId = downloadItems[0].id;
    let gettingIcon = browser.downloads.getFileIcon(latestDownloadId);
    gettingIcon.then(gotIcon, onError);
  }
}

let searching = browser.downloads.search({
  limit: 1,
  orderBy: ["-startTime"],
});

searching.then(getIcon, onError);
```

### Example extensions

* latest-download

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.onErased
==================

The **`onErased()`** event of the `downloads` API fires when a download is erased from the browser history.

The listener is passed the `downloadId` of the `downloads.DownloadItem` object in question as a parameter.

Syntax
------


```js
browser.downloads.onErased.addListener(listener)
browser.downloads.onErased.removeListener(listener)
browser.downloads.onErased.hasListener(listener)
```


Events have three functions:

`addListener(listener)`

Adds a listener to this event.

`removeListener(listener)`

Stop listening to this event. The `listener` argument is the listener to remove.

`hasListener(listener)`

Check whether a given `listener` is registered for this event. Returns `true` if it is listening, `false` otherwise.

addListener syntax
------------------

### Parameters

`listener`

The function called when this event occurs. This function is passed this argument:

`downloadId`

An `integer` representing the `id` of the `downloads.DownloadItem` that was erased.


Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

Add a listener for `onErased` events, then erase the most recent download:


```js
function handleErased(item) {
  console.log(`Erased: ${item}`);
}

browser.downloads.onErased.addListener(handleErased);

let erasing = browser.downloads.erase({
  limit: 1,
  orderBy: ["-startTime"],
});
```


**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.resume()
==================

The **`resume()`** function of the `downloads` API resumes a paused download. If the request was successful, the download will be unpaused and progress will resume. The `resume()` call will fail if the download is not active: for example, because it has finished downloading.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let resuming = browser.downloads.resume(
  downloadId      // integer
)
```

### Parameters

`downloadId`

An `integer` representing the `id` of the download to resume.

### Return value

A `Promise`. If the request was successful, the promise will be fulfilled with no arguments. If the request failed, the promise will be rejected with an error message.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------


```js
let downloadId = 2;

function onResumed() {
  console.log(`Resumed download`);
}

function onError(error) {
  console.log(`Error: ${error}`);
}

let resuming = browser.downloads.resume(downloadId);
resuming.then(onResumed, onError);
```


**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.InterruptReason
=========================

The `InterruptReason` type of the `downloads` API defines a set of possible reasons why a download was interrupted.

A `downloads.DownloadItem`'s `error` property will contain a string taken from the values defined in this type.

Type
----

Values of this type are strings. Possible values are split into categories, with each set having the same substring at the beginning:

File-related errors:

* `"FILE_FAILED"`
* `"FILE_ACCESS_DENIED"`
* `"FILE_NO_SPACE"`
* `"FILE_NAME_TOO_LONG"`
* `"FILE_TOO_LARGE"`
* `"FILE_VIRUS_INFECTED"`
* `"FILE_TRANSIENT_ERROR"`
* `"FILE_BLOCKED"`
* `"FILE_SECURITY_CHECK_FAILED"`
* `"FILE_TOO_SHORT"`

Network-related errors:

* `"NETWORK_FAILED"`
* `"NETWORK_TIMEOUT"`
* `"NETWORK_DISCONNECTED"`
* `"NETWORK_SERVER_DOWN"`
* `"NETWORK_INVALID_REQUEST"`

Server-related errors:

* `"SERVER_FAILED"`
* `"SERVER_NO_RANGE"`
* `"SERVER_BAD_CONTENT"`
* `"SERVER_UNAUTHORIZED"`
* `"SERVER_CERT_PROBLEM"`
* `"SERVER_FORBIDDEN"`

User-related errors:

* `"USER_CANCELED"`
* `"USER_SHUTDOWN"`

Miscellaneous:

* `"CRASH"`
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.DownloadTime
======================

The `DownloadTime` type of the `downloads` API represents the time a download took to complete.

Type
----

A `DownloadTime` can be one of three different types:

* a JavaScript `Date` object.
* a string:
    + if this contains only digits, it's interpreted as the number of milliseconds since the UNIX epoch.
    + otherwise, it's interpreted as an ISO 8601 string.
* a number: this is interpreted as the number of milliseconds since the UNIX epoch.
Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.FilenameConflictAction
================================

The `FilenameConflictAction` type of the `downloads` API specifies what to do if the name of a downloaded file conflicts with an existing file.

This type defines the values that can be used for the `conflictAction` property of the `downloads.download` function's `options` parameter.

Type
----

Values of this type are strings. Possible values are:

`"uniquify"`

The browser will modify the filename to make it unique.

`"overwrite"`

The browser will overwrite the old file with the newly-downloaded file.

`"prompt"`

The browser will prompt the user, asking them to choose whether to uniquify or overwrite.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.search()
==================

The **`search()`** function of the `downloads` API queries the `DownloadItems` available in the browser's downloads manager, and returns those that match the specified search criteria.

This is an asynchronous function that returns a `Promise`.

Syntax
------


```js
let searching = browser.downloads.search(query);
```

### Parameters

`query`

A `downloads.DownloadQuery` object.

### Return value

A `Promise`. The promise is fulfilled with an `array` of ``downloads.DownloadItem`` objects that match the given criteria.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

Examples
--------

In general, you restrict the items retrieved using the `query` parameter.

### Get downloads matching "query"


```js
function logDownloads(downloads) {
  for (const download of downloads) {
    console.log(download.id);
    console.log(download.url);
  }
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.downloads
  .search({
    query: ["imgur"],
  })
  .then(logDownloads, onError);
```

### Get a specific item

To get a specific `DownloadItem`, the easiest way is to set only the `id` field, as seen in the snippet below:


```js
function logDownloads(downloads) {
  for (const download of downloads) {
    console.log(download.id);
    console.log(download.url);
  }
}

function onError(error) {
  console.log(`Error: ${error}`);
}

const id = 13;

browser.downloads.search({ id }).then(logDownloads, onError);
```

### Get all downloads

If you want to return all `DownloadItems`, set `query` to an empty object.


```js
function logDownloads(downloads) {
  for (const download of downloads) {
    console.log(download.id);
    console.log(download.url);
  }
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.downloads.search({}).then(logDownloads, onError);
```

### Get the most recent download

You can get the most recent download by specifying the following search parameters:


```js
function logDownloads(downloads) {
  for (const download of downloads) {
    console.log(download.id);
    console.log(download.url);
  }
}

function onError(error) {
  console.log(`Error: ${error}`);
}

browser.downloads
  .search({
    limit: 1,
    orderBy: ["-startTime"],
  })
  .then(logDownloads, onError);
```


You can see this code in action in our latest-download example.

### Example extensions

* latest-download

**Note:** This API is based on Chromium's `chrome.downloads` API.
downloads.BooleanDelta
======================

The `BooleanDelta` type of the `downloads` API represents the difference between two booleans.

Type
----

Values of this type are objects. They contain the following properties:

`current` Optional

A `boolean` representing the current boolean value.

`previous` Optional

A `boolean` representing the previous boolean value.

Browser compatibility
---------------------

BCD tables only load in the browser with JavaScript enabled. Enable JavaScript to view data.

**Note:** This API is based on Chromium's `chrome.downloads` API.