Skip to content

add api docs to GM_download with browser api #74

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Tyarel8 wants to merge 2 commits into
base: source
Choose a base branch
from
+35 −4
Open

add api docs to GM_download with browser api #74

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
128e50d
add api docs to GM_download with native api
Tyarel8 Jun 18, 2026
30941bf
update docs
Tyarel8 Jun 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 35 additions & 4 deletions content/pages/api/gm.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -626,6 +626,13 @@ The response object is passed to each event handler with the following propertie

Downloads a URL to a local file.

By default the download is performed via XMLHttpRequest (like `GM_xmlhttpRequest`).

When the **"Use browser download API"** option is enabled in Violentmonkey's Advanced
settings, the download is delegated to the browser's native download manager
(`browser.downloads.download`) instead, skipping XHR. This mode allows
filenames with subfolders and to show progress in the browser's download bar.

1. using an object:

```js
Expand All @@ -640,10 +647,31 @@ Downloads a URL to a local file.

- <Field name="name" type="string" />

The filename to save to. Folders/subpaths aren't supported yet.
The filename to save to. When using the browser download API, subfolder
paths (e.g. `"sub/file.txt"`) are supported if using the browser download api.

Most [GM_xmlhttpRequest](#gm_xmlhttprequest) options are supported.

When using the browser download API, the following additional options
are also available:

- <Field name="saveAs?" type="boolean" />

Show a "Save As" dialog regardless of the browser's download preferences.

- <Field name="conflictAction?" type="string" />

Action when a file with the same name already exists:
`"uniquify"` (default), `"overwrite"`, or `"prompt"`.

- <Field name="method?" type="string" />

HTTP method for the download request (e.g. `"GET"`, `"POST"`).

- <Field name="body?" type="string" />

Request body to send with the download request.

- <Field name="headers?" type="object" />
- <Field name="timeout?" type="number" comment="since VM2.9.5" />
- <Field name="context?" type="any" comment="since VM2.13.4" />
Expand All @@ -659,7 +687,8 @@ Downloads a URL to a local file.
- <Field name="onreadystatechange?" type="() => void" comment="since VM2.13.4" />
- <Field name="ontimeout?" type="() => void" />

The `onload` event handler is called after the data is downloaded from URL, before writing the file.
The `onload` event handler is called after the data is downloaded from URL,
before writing the file (XHR path only; ignored when using the browser API).

2. using separate parameters:

Expand All @@ -673,13 +702,15 @@ Downloads a URL to a local file.

- <Field name="name" type="string" />

The filename to save to. Folders/subpaths aren't supported yet.
The filename to save to.

Returns a control object with the following properties, same as [GM_xmlhttpRequest](#gm_xmlhttprequest):

- <Field name="abort" type="() => void" />

A function to abort the request.
A function to abort the request (XHR path only; no-op when using the browser API).

When using `GM.download`, the returned Promise resolves when the download completes.

## GM.*

Expand Down