From 128e50d27f385af8e45c831fd8578bf37ad78fd2 Mon Sep 17 00:00:00 2001 From: Tyarel8 <98483313+Tyarel8@users.noreply.github.com> Date: Thu, 18 Jun 2026 11:09:17 +0200 Subject: [PATCH 1/2] add api docs to GM_download with native api --- content/pages/api/gm.mdx | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/content/pages/api/gm.mdx b/content/pages/api/gm.mdx index a67d6d87..443420b5 100644 --- a/content/pages/api/gm.mdx +++ b/content/pages/api/gm.mdx @@ -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 `nativeDownload` option is enabled, the download is delegated to the browser's +native download manager instead, skipping XHR entirely. + +The native download path can be enabled globally in Violentmonkey's Advanced settings +or on a per-call basis with the `nativeDownload` option. + 1. using an object: ```js @@ -644,6 +651,19 @@ Downloads a URL to a local file. Most [GM_xmlhttpRequest](#gm_xmlhttprequest) options are supported. + - + + When `true`, the download is delegated to the browser's native download + manager (`browser.downloads.download`). + + Event handlers (`onload`, `onprogress`, etc.) are **not called** when + native download is used — there is no XHR response object. Use `onerror` + to catch failures, or await the returned Promise when using `GM.download`. + + This option can also be enabled globally in Violentmonkey's settings, + in which case every `GM_download` call uses the native path unless + `nativeDownload: false` is explicitly set. + - - - @@ -659,7 +679,8 @@ Downloads a URL to a local file. - - - 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 for native downloads). 2. using separate parameters: @@ -681,6 +702,9 @@ Returns a control object with the following properties, same as [GM_xmlhttpReque A function to abort the request. +When using `GM.download`, the returned Promise resolves when the download completes +(on the XHR path) or when the browser starts the native download (on the native path). + ## GM.* `GM` *(since VM2.12.0)* is a single variable with [Greasemonkey4-compatible](https://wiki.greasespot.net/Greasemonkey_Manual:API) aliases, the `async` functions return a `Promise` that's resolved with the returned value. From 30941bf711a2070fd5e598d724739da102c8f967 Mon Sep 17 00:00:00 2001 From: Tyarel8 <98483313+Tyarel8@users.noreply.github.com> Date: Thu, 18 Jun 2026 18:52:04 +0200 Subject: [PATCH 2/2] update docs --- content/pages/api/gm.mdx | 45 +++++++++++++++++++++++----------------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/content/pages/api/gm.mdx b/content/pages/api/gm.mdx index 443420b5..61c47fcc 100644 --- a/content/pages/api/gm.mdx +++ b/content/pages/api/gm.mdx @@ -627,11 +627,11 @@ 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 `nativeDownload` option is enabled, the download is delegated to the browser's -native download manager instead, skipping XHR entirely. -The native download path can be enabled globally in Violentmonkey's Advanced settings -or on a per-call basis with the `nativeDownload` option. +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: @@ -647,22 +647,30 @@ or on a per-call basis with the `nativeDownload` option. - - 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: - When `true`, the download is delegated to the browser's native download - manager (`browser.downloads.download`). + - - Event handlers (`onload`, `onprogress`, etc.) are **not called** when - native download is used — there is no XHR response object. Use `onerror` - to catch failures, or await the returned Promise when using `GM.download`. + Show a "Save As" dialog regardless of the browser's download preferences. - This option can also be enabled globally in Violentmonkey's settings, - in which case every `GM_download` call uses the native path unless - `nativeDownload: false` is explicitly set. + - + + Action when a file with the same name already exists: + `"uniquify"` (default), `"overwrite"`, or `"prompt"`. + + - + + HTTP method for the download request (e.g. `"GET"`, `"POST"`). + + - + + Request body to send with the download request. - - @@ -680,7 +688,7 @@ or on a per-call basis with the `nativeDownload` option. - The `onload` event handler is called after the data is downloaded from URL, - before writing the file (XHR path only; ignored for native downloads). + before writing the file (XHR path only; ignored when using the browser API). 2. using separate parameters: @@ -694,16 +702,15 @@ or on a per-call basis with the `nativeDownload` option. - - 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): - - 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 -(on the XHR path) or when the browser starts the native download (on the native path). +When using `GM.download`, the returned Promise resolves when the download completes. ## GM.*