Properties

• current

  boolean optional

• previous

  boolean optional

Enum

Properties

• current

  number optional

• previous

  number optional

Properties

• canResume

  BooleanDelta optional

  The change incanResume, if any.

• danger

  StringDelta optional

  The change indanger, if any.

• endTime

  StringDelta optional

  The change inendTime, if any.

• error

  StringDelta optional

  The change inerror, if any.

• exists

  BooleanDelta optional

  The change inexists, if any.

• fileSize

  DoubleDelta optional

  The change infileSize, if any.

• filename

  StringDelta optional

  The change infilename, if any.

• finalUrl

  StringDelta optional

  Chrome 54+

  The change infinalUrl, if any.

• id

  number

  Theid of theDownloadItem that changed.

• mime

  StringDelta optional

  The change inmime, if any.

• paused

  BooleanDelta optional

  The change inpaused, if any.

• startTime

  StringDelta optional

  The change instartTime, if any.

• state

  StringDelta optional

  The change instate, if any.

• totalBytes

  DoubleDelta optional

  The change intotalBytes, if any.

• url

  StringDelta optional

  The change inurl, if any.

Properties

• byExtensionId

  string optional

  The identifier for the extension that initiated this download if this download was initiated by an extension. Does not change once it is set.

• byExtensionName

  string optional

  The localized name of the extension that initiated this download if this download was initiated by an extension. May change if the extension changes its name or if the user changes their locale.

• bytesReceived

  number

  Number of bytes received so far from the host, without considering file compression.

• canResume

  boolean

  True if the download is in progress and paused, or else if it is interrupted and can be resumed starting from where it was interrupted.

• danger

  DangerType

  Indication of whether this download is thought to be safe or known to be suspicious.

• endTime

  string optional

  The time when the download ended in ISO 8601 format. May be passed directly to the Date constructor:chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.endTime) console.log(new Date(item.endTime))})})

• error

  InterruptReason optional

  Why the download was interrupted. Several kinds of HTTP errors may be grouped under one of the errors beginning withSERVER_. Errors relating to the network begin withNETWORK_, errors relating to the process of writing the file to the file system begin withFILE_, and interruptions initiated by the user begin withUSER_.

• estimatedEndTime

  string optional

  Estimated time when the download will complete in ISO 8601 format. May be passed directly to the Date constructor:chrome.downloads.search({}, function(items){items.forEach(function(item){if (item.estimatedEndTime) console.log(new Date(item.estimatedEndTime))})})

• exists

  boolean

  Whether the downloaded file still exists. This information may be out of date because Chrome does not automatically watch for file removal. Callsearch() in order to trigger the check for file existence. When the existence check completes, if the file has been deleted, then anonChanged event will fire. Note thatsearch() does not wait for the existence check to finish before returning, so results fromsearch() may not accurately reflect the file system. Also,search() may be called as often as necessary, but will not check for file existence any more frequently than once every 10 seconds.

• fileSize

  number

  Number of bytes in the whole file post-decompression, or -1 if unknown.

• filename

  string

  Absolute local path.

• finalUrl

  string

  Chrome 54+

  The absolute URL that this download is being made from, after all redirects.

• id

  number

  An identifier that is persistent across browser sessions.

• incognito

  boolean

  False if this download is recorded in the history, true if it is not recorded.

• mime

  string

  The file's MIME type.

• paused

  boolean

  True if the download has stopped reading data from the host, but kept the connection open.

• referrer

  string

  Absolute URL.

• startTime

  string

  The time when the download began in ISO 8601 format. May be passed directly to the Date constructor:chrome.downloads.search({}, function(items){items.forEach(function(item){console.log(new Date(item.startTime))})})

• state

  State

  Indicates whether the download is progressing, interrupted, or complete.

• totalBytes

  number

  Number of bytes in the whole file, without considering file compression, or -1 if unknown.

• url

  string

  The absolute URL that this download initiated from, before any redirects.

Properties

• body

  string optional

  Post body.

• conflictAction

  FilenameConflictAction optional

  The action to take iffilename already exists.

• filename

  string optional

  A file path relative to the Downloads directory to contain the downloaded file, possibly containing subdirectories. Absolute paths, empty paths, and paths containing back-references ".." will cause an error.onDeterminingFilename allows suggesting a filename after the file's MIME type and a tentative filename have been determined.

• headers

  HeaderNameValuePair[] optional

  Extra HTTP headers to send with the request if the URL uses the HTTP[s] protocol. Each header is represented as a dictionary containing the keysname and eithervalue orbinaryValue, restricted to those allowed by XMLHttpRequest.

• method

  HttpMethod optional

  The HTTP method to use if the URL uses the HTTP[S] protocol.

• saveAs

  boolean optional

  Use a file-chooser to allow the user to select a filename regardless of whetherfilename is set or already exists.

• url

  string

  The URL to download.

Properties

• bytesReceived

  number optional

  Number of bytes received so far from the host, without considering file compression.

• danger

  DangerType optional

  Indication of whether this download is thought to be safe or known to be suspicious.

• endTime

  string optional

  The time when the download ended in ISO 8601 format.

• endedAfter

  string optional

  Limits results toDownloadItem that ended after the given ms in ISO 8601 format

• endedBefore

  string optional

  Limits results toDownloadItem that ended before the given ms in ISO 8601 format.

• error

  InterruptReason optional

  Why a download was interrupted.

• exists

  boolean optional

  Whether the downloaded file exists;

• fileSize

  number optional

  Number of bytes in the whole file post-decompression, or -1 if unknown.

• filename

  string optional

  Absolute local path.

• filenameRegex

  string optional

  Limits results toDownloadItem whosefilename matches the given regular expression.

• finalUrl

  string optional

  Chrome 54+

  The absolute URL that this download is being made from, after all redirects.

• finalUrlRegex

  string optional

  Chrome 54+

  Limits results toDownloadItem whosefinalUrl matches the given regular expression.

• id

  number optional

  Theid of theDownloadItem to query.

• limit

  number optional

  The maximum number of matchingDownloadItem returned. Defaults to 1000. Set to 0 in order to return all matchingDownloadItem. Seesearch for how to page through results.

• mime

  string optional

  The file's MIME type.

• orderBy

  string[] optional

  Set elements of this array toDownloadItem properties in order to sort search results. For example, settingorderBy=['startTime'] sorts theDownloadItem by their start time in ascending order. To specify descending order, prefix with a hyphen: '-startTime'.

• paused

  boolean optional

  True if the download has stopped reading data from the host, but kept the connection open.

• query

  string[] optional

  This array of search terms limits results toDownloadItem whosefilename orurl orfinalUrl contain all of the search terms that do not begin with a dash '-' and none of the search terms that do begin with a dash.

• startTime

  string optional

  The time when the download began in ISO 8601 format.

• startedAfter

  string optional

  Limits results toDownloadItem that started after the given ms in ISO 8601 format.

• startedBefore

  string optional

  Limits results toDownloadItem that started before the given ms in ISO 8601 format.

• state

  State optional

  Indicates whether the download is progressing, interrupted, or complete.

• totalBytes

  number optional

  Number of bytes in the whole file, without considering file compression, or -1 if unknown.

• totalBytesGreater

  number optional

  Limits results toDownloadItem whosetotalBytes is greater than the given integer.

• totalBytesLess

  number optional

  Limits results toDownloadItem whosetotalBytes is less than the given integer.

• url

  string optional

  The absolute URL that this download initiated from, before any redirects.

• urlRegex

  string optional

  Limits results toDownloadItem whoseurl matches the given regular expression.

uniquify

To avoid duplication, thefilename is changed to include a counter before the filename extension.

overwrite

The existing file will be overwritten with the new file.

prompt

The user will be prompted with a file chooser dialog.

Enum

Properties

• conflictAction

  FilenameConflictAction optional

  The action to take iffilename already exists.

• filename

  string

  TheDownloadItem's new targetDownloadItem.filename, as a path relative to the user's default Downloads directory, possibly containing subdirectories. Absolute paths, empty paths, and paths containing back-references ".." will be ignored.filename is ignored if there are anyonDeterminingFilename listeners registered by any extensions.

Properties

• size

  number optional

  The size of the returned icon. The icon will be square with dimensions size * size pixels. The default and largest size for the icon is 32x32 pixels. The only supported sizes are 16 and 32. It is an error to specify any other size.

Properties

• name

  string

  Name of the HTTP header.

• value

  string

  Value of the HTTP header.

Enum

Enum

in_progress

The download is currently receiving data from the server.

interrupted

An error broke the connection with the file host.

complete

The download completed successfully.

Enum

Properties

• current

  string optional

• previous

  string optional

Properties

• enabled

  boolean

  Enable or disable the download UI.

chrome.downloads.acceptDanger(
  downloadId: number,
): Promise<void>

Prompt the user to accept a dangerous download. Can only be called from a visible context (tab, window, or page/browser action popup). Does not automatically accept dangerous downloads. If the download is accepted, then anonChanged event will fire, otherwise nothing will happen. When all the data is fetched into a temporary file and either the download is not dangerous or the danger has been accepted, then the temporary file is renamed to the target filename, thestate changes to 'complete', andonChanged fires.

Parameters

• downloadId

  number

  The identifier for theDownloadItem.

Returns

• Promise<void>

  Chrome 96+

chrome.downloads.cancel(
  downloadId: number,
): Promise<void>

Cancel a download. Whencallback is run, the download is cancelled, completed, interrupted or doesn't exist anymore.

Parameters

• downloadId

  number

  The id of the download to cancel.

Returns

• Promise<void>

  Chrome 96+

chrome.downloads.download(
  options: DownloadOptions,
): Promise<number>

Download a URL. If the URL uses the HTTP[S] protocol, then the request will include all cookies currently set for its hostname. If bothfilename andsaveAs are specified, then the Save As dialog will be displayed, pre-populated with the specifiedfilename. If the download started successfully,callback will be called with the newDownloadItem'sdownloadId. If there was an error starting the download, thencallback will be called withdownloadId=undefined andruntime.lastError will contain a descriptive string. The error strings are not guaranteed to remain backwards compatible between releases. Extensions must not parse it.

Parameters

• options

  DownloadOptions

  What to download and how.

Returns

• Promise<number>

  Chrome 96+

chrome.downloads.erase(
  query: DownloadQuery,
): Promise<number[]>

Erase matchingDownloadItem from history without deleting the downloaded file. AnonErased event will fire for eachDownloadItem that matchesquery, thencallback will be called.

Parameters

• query

  DownloadQuery

Returns

• Promise<number[]>

  Chrome 96+

chrome.downloads.getFileIcon(
  downloadId: number,
  options?: GetFileIconOptions,
): Promise<string | undefined>

Retrieve an icon for the specified download. For new downloads, file icons are available after theonCreated 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 operating system or toolkit depending on the 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. If a file icon cannot be determined,runtime.lastError will contain an error message.

Parameters

• downloadId

  number

  The identifier for the download.

• options

  GetFileIconOptions optional

Returns

• Promise<string | undefined>

  Chrome 96+

chrome.downloads.open(
  downloadId: number,
): Promise<void>

Opens the downloaded file now if theDownloadItem is complete; otherwise returns an error throughruntime.lastError. This method requires the"downloads.open" permission in addition to the"downloads" permission. AnonChanged event fires when the item is opened for the first time. This method can only be called in response to a user gesture.

Parameters

• downloadId

  number

  The identifier for the downloaded file.

Returns

• Promise<void>

  Chrome 123+

chrome.downloads.pause(
  downloadId: number,
): Promise<void>

Pause the download. If the request was successful the download is in a paused state. Otherwiseruntime.lastError contains an error message. The request will fail if the download is not active.

Parameters

• downloadId

  number

  The id of the download to pause.

Returns

• Promise<void>

  Chrome 96+

chrome.downloads.removeFile(
  downloadId: number,
): Promise<void>

Remove the downloaded file if it exists and theDownloadItem is complete; otherwise return an error throughruntime.lastError.

Parameters

• downloadId

  number

Returns

• Promise<void>

  Chrome 96+

chrome.downloads.resume(
  downloadId: number,
): Promise<void>

Resume a paused download. If the request was successful the download is in progress and unpaused. Otherwiseruntime.lastError contains an error message. The request will fail if the download is not active.

Parameters

• downloadId

  number

  The id of the download to resume.

Returns

• Promise<void>

  Chrome 96+

chrome.downloads.search(
  query: DownloadQuery,
): Promise<DownloadItem[]>

FindDownloadItem. Setquery to the empty object to get allDownloadItem. To get a specificDownloadItem, set only theid field. To page through a large number of items, setorderBy: ['-startTime'], setlimit to the number of items per page, and setstartedAfter to thestartTime of the last item from the last page.

Parameters

• query

  DownloadQuery

Returns

• Promise<DownloadItem[]>

  Chrome 96+

chrome.downloads.setShelfEnabled(
  enabled: boolean,
): void

UsesetUiOptions instead.

Enable or disable 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. Enabling the shelf while at least one other extension has disabled it will return an error throughruntime.lastError. Requires the"downloads.shelf" permission in addition to the"downloads" permission.

Parameters

• enabled

  boolean

chrome.downloads.setUiOptions(
  options: UiOptions,
): Promise<void>

Change the download UI of every window associated with the current browser profile. As long as at least one extension has setUiOptions.enabled to false, the download UI will be hidden. SettingUiOptions.enabled to true while at least one other extension has disabled it will return an error throughruntime.lastError. Requires the"downloads.ui" permission in addition to the"downloads" permission.

Parameters

• options

  UiOptions

  Encapsulate a change to the download UI.

Returns

• Promise<void>

chrome.downloads.show(
  downloadId: number,
): void

Show the downloaded file in its folder in a file manager.

Parameters

• downloadId

  number

  The identifier for the downloaded file.

chrome.downloads.showDefaultFolder(): void

Show the default Downloads folder in a file manager.

chrome.downloads.onChanged.addListener(
  callback: function,
)

When any of aDownloadItem's properties exceptbytesReceived andestimatedEndTime changes, this event fires with thedownloadId and an object containing the properties that changed.

Parameters

• callback

  function

  Thecallback parameter looks like:

  (downloadDelta: DownloadDelta) => void

  • downloadDelta

    DownloadDelta

chrome.downloads.onCreated.addListener(
  callback: function,
)

This event fires with theDownloadItem object when a download begins.

Parameters

• callback

  function

  Thecallback parameter looks like:

  (downloadItem: DownloadItem) => void

  • downloadItem

    DownloadItem

chrome.downloads.onDeterminingFilename.addListener(
  callback: function,
)

During the filename determination process, extensions will be given the opportunity to override the targetDownloadItem.filename. Each extension may not register more than one listener for this event. Each listener must callsuggest exactly once, either synchronously or asynchronously. If the listener callssuggest asynchronously, then it must returntrue. If the listener neither callssuggest synchronously nor returnstrue, thensuggest will be called automatically. TheDownloadItem will not complete until all listeners have calledsuggest. Listeners may callsuggest without any arguments in order to allow the download to usedownloadItem.filename for its filename, or pass asuggestion object tosuggest in order to override the target filename. If more than one extension overrides the filename, then the last extension installed whose listener passes asuggestion object tosuggest wins. In order to avoid confusion regarding which extension will win, users should not install extensions that may conflict. If the download is initiated bydownload and the target filename is known before the MIME type and tentative filename have been determined, passfilename todownload instead.

Parameters

• callback

  function

  Thecallback parameter looks like:

  (downloadItem: DownloadItem, suggest: function) => void

  • downloadItem

    DownloadItem

  • suggest

    function

    Thesuggest parameter looks like:

    (suggestion?: FilenameSuggestion) => void

    • suggestion

      FilenameSuggestion optional

chrome.downloads.onErased.addListener(
  callback: function,
)

Fires with thedownloadId when a download is erased from history.

Parameters

• callback

  function

  Thecallback parameter looks like:

  (downloadId: number) => void

  • downloadId

    number