Violentmonkey

https://violentmonkey.github.io
Admin
Violentmonkey is an open source userscript manager that allows you to customize and automate web...
Tokens:19,494
Snippets:245
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Blacklist Configuration Example

Source: https://violentmonkey.github.io/posts/smart-rules-for-blacklist

This example demonstrates how to configure a blacklist using hostnames, @exclude-match, and @exclude rules. Comments are ignored.

```userscript
# hostnames
www.google.com

# @exclude-match rules
*://twitter.com/*

# @exclude rules
@exclude https://example.com/*

```

--------------------------------

### Whitelist Configuration Example

Source: https://violentmonkey.github.io/posts/smart-rules-for-blacklist

This example shows how to set up a whitelist using @match and @include rules, followed by a catch-all rule to block other URLs. This effectively disables scripts on all sites except those explicitly whitelisted.

```userscript
# match rules
@match https://www.google.com/*

# include rules
@include https://example.com/*

# block everything else
*

```

--------------------------------

### Start Development Server

Source: https://violentmonkey.github.io/guide/using-modern-syntax

Run this command to start the development server. It watches for changes in your source code and recompiles it to the dist directory.

```bash
$ npm run dev
```

--------------------------------

### Install @violentmonkey/shortcut with NPM

Source: https://violentmonkey.github.io/guide/keyboard-shortcuts

Install the @violentmonkey/shortcut library as a project dependency using NPM. This method is recommended for projects using a bundler and TypeScript.

```bash
$ npm i @violentmonkey/shortcut

```

--------------------------------

### Register a simple keyboard shortcut

Source: https://violentmonkey.github.io/guide/keyboard-shortcuts

Use the `register` function from VM.shortcut to bind a key combination to a callback function. This example registers 'Ctrl-I'.

```javascript
VM.shortcut.register('c-i', () => {
  console.log('You just pressed Ctrl-I');
});

```

--------------------------------

### Register a key sequence shortcut

Source: https://violentmonkey.github.io/guide/keyboard-shortcuts

The library supports registering sequences of key presses. This example registers the sequence 'Ctrl-A' followed by 'Ctrl-B'.

```javascript
VM.shortcut.register('c-a c-b', () => {
  console.log('You just pressed Ctrl-A Ctrl-B sequence');
});

```

--------------------------------

### Basic @include and @exclude Rules

Source: https://violentmonkey.github.io/api/matching

Shows examples of @include and @exclude rules using normal strings with wildcards and as regular expressions.

```javascript
// @include *
// @include https://www.google.com/*
// @include /\.com\.hk\//
```

```javascript
// @exclude https://www.google.com/exact/url
```

--------------------------------

### Demonstration of Synchronous vs. Asynchronous Injection

Source: https://violentmonkey.github.io/posts/inject-scripts-with-blob-urls

This example demonstrates the difference in execution order between `textContent` injection (synchronous) and Blob URL injection (asynchronous). The asynchronous script logs its output last.

```javascript
{
  const s = document.createElement('script');
  s.textContent = 'console.log(1)';
  document.body.appendChild(s);
  document.body.removeChild(s);
}

{
  const s = document.createElement('script');
  const b = new Blob(['console.log(2)'], { type: 'text/javascript' });
  const u = URL.createObjectURL(b);
  s.src = u;
  document.body.appendChild(s);
  document.body.removeChild(s);
  URL.revokeObjectURL(u);
}

console.log(3);
```

--------------------------------

### Basic Metadata Block Structure

Source: https://violentmonkey.github.io/api/metadata-block

The metadata block must start with `// ==UserScript==` and end with `// ==/UserScript==`. Each line within the block must begin with `//` and have exactly one space after it. Place the metadata block at the very beginning of the file.

```javascript
// ==UserScript==
// @key value
// ==/UserScript==

```

--------------------------------

### Provide Support URL - @supportURL

Source: https://violentmonkey.github.io/api/metadata-block

The @supportURL metadata key provides a link to where users can get support for the script, displayed via an icon in the user scripts list.

```javascript
// @supportURL https://violentmonkey.github.io/
```

--------------------------------

### Import @violentmonkey/shortcut after NPM installation

Source: https://violentmonkey.github.io/guide/keyboard-shortcuts

After installing @violentmonkey/shortcut via NPM, you can import its functions directly into your code.

```javascript
import { register } from '@violentmonkey/shortcut';

```

--------------------------------

### GM.xmlHttpRequest with Abort Control (VM2.18.3+)

Source: https://violentmonkey.github.io/api/gm

This example shows how to get a control object from GM.xmlHttpRequest in VM2.18.3+ and Tampermonkey, allowing you to abort the request. The request can then be awaited.

```javascript
// VM2.18.3+, TM
const control = GM.xmlHttpRequest({ url });
myButton.addEventListener('click', control.abort, { once: true });
const res = await control;
```

--------------------------------

### GM.download

Source: https://violentmonkey.github.io/api/gm

Initiates a file download.

```APIDOC
## GM.download

### Description
Initiates a file download.

### Method
`GM.download` (async)
```

--------------------------------

### Create New Script Directory

Source: https://violentmonkey.github.io/guide/using-modern-syntax

Use these commands to create a new directory for your userscript project and navigate into it.

```bash
$ mkdir my-script
$ cd my-script
```

--------------------------------

### Download URL to Local File with GM_download (Separate Parameters)

Source: https://violentmonkey.github.io/api/gm

Download a URL to a local file by providing the URL and filename as separate parameters to GM_download. This is a simpler way to initiate a download when advanced options are not needed.

```javascript
GM_download(url, name)
```

--------------------------------

### Basic @match and @exclude-match Rules

Source: https://violentmonkey.github.io/api/matching

Demonstrates the basic syntax for @match and @exclude-match rules, which are recommended for their safety and strictness.

```javascript
// @match *://*/*
// @exclude-match *://*.tk/*
```

--------------------------------

### Generate Userscript Project

Source: https://violentmonkey.github.io/guide/using-modern-syntax

This command initializes a new userscript project using Yeoman and the Violentmonkey generator, setting up a JavaScript toolchain with Babel and Rollup.

```bash
$ npx -p github:violentmonkey/generator-userscript -p yo yo @violentmonkey/userscript
```

--------------------------------

### Download URL to Local File with GM_download (Object Options)

Source: https://violentmonkey.github.io/api/gm

Initiate a download of a URL to a local file using GM_download with an options object. This method supports various configurations similar to GM_xmlhttpRequest, including headers, timeout, and event handlers for download progress and completion.

```javascript
GM_download(options)
```

--------------------------------

### GM.openInTab

Source: https://violentmonkey.github.io/api/gm

Opens a URL in a new tab.

```APIDOC
## GM.openInTab

### Description
Opens a URL in a new tab.

### Method
`GM.openInTab`
```

--------------------------------

### Build Userscript for Production

Source: https://violentmonkey.github.io/guide/using-modern-syntax

Execute this command to compile your source code once for production. The compiled script will be saved in the dist directory.

```bash
$ npm run build
```

--------------------------------

### Update Menu Command In-Place

Source: https://violentmonkey.github.io/api/gm

Demonstrates how to change a menu command in-place by using its existing ID, preserving its position. If in-place update is not supported, it shows how to unregister and re-register commands.

```javascript
const id = 'status';
const inplace = id === GM_registerMenuCommand('Enabled', onClick, { id });
if (inplace) {
  // supported: change the command in-place using the same `id`
  GM_registerMenuCommand('Disabled', onClick, { id, title: 'Status' });
} else {
  // not supported: recreate the commands
  GM_unregisterMenuCommand('Enabled');
  GM_unregisterMenuCommand('Foo');
  GM_unregisterMenuCommand('Bar');
  GM_registerMenuCommand('Disabled', onClick);
  GM_registerMenuCommand('Foo', onClick2);
  GM_registerMenuCommand('Bar', onClick3);
}
```

--------------------------------

### Script Description with Localization

Source: https://violentmonkey.github.io/api/metadata-block

The `@description` key provides a summary of the script. It can be localized using `@description:localeCode`.

```javascript
// @description         This script rocks.
// @description:zh-CN   这个脚本很棒！

```

--------------------------------

### GM_openInTab

Source: https://violentmonkey.github.io/api/gm

Opens a URL in a new tab, with options for controlling its behavior.

```APIDOC
## GM_openInTab

### Description
Opens URL in a new tab.

### Method Signature (Object Options)
```javascript
let tabControl = GM_openInTab(url, options)
```

### Parameters (Object Options)
*   **url** : string
The URL to open in a new tab. URL relative to current page is also allowed. Note that Firefox disallows `data:`, `blob:`, `chrome:`, `file:`, and many `about:` URLs.
*   **options?** : object
    *   **active** : boolean = true
        Make the new tab active (i.e. open in foreground).
    *   **container?** : number - since VM2.12.5, Firefox-only
        Set tab’s container in Firefox:
        *   not specified = reuse script’s tab container
        *   `0` = default (main) container
        *   `1`, `2`, etc. = internal container index
    *   **insert** : boolean = true - since VM2.11.0
        Insert the new tab next to the current tab and set its “openerTab” so when it’s closed the original tab will be focused automatically. When `false` or not specified, the usual browser behavior is to open the tab at the end of the tab list.
    *   **pinned** : boolean = false - since VM2.12.5
        Pin the tab (i.e. show without a title at the beginning of the tab list).

### Method Signature (Boolean Option)
```javascript
let tabControl = GM_openInTab(url, openInBackground)
```

### Parameters (Boolean Option)
*   **openInBackground** : boolean
    Open the tab in background. Note, this is a reverse of the first usage method so for example `true` is the same as `{ active: false }`.

### Returns
An object with following properties:
*   **onclose?** : () => void
    Сan be assigned to a function. If provided, it will be called when the opened tab is closed.
*   **closed** : boolean
    Whether the opened tab is closed.
*   **close** : () => void
    A function to explicitly close the opened tab.

### Example
```javascript
let tabControl = GM_openInTab(url);
tabContro.onclose = () => console.log('tab is closed');
tabContro.close();
```
```

--------------------------------

### Specify Script Download URL - @downloadURL

Source: https://violentmonkey.github.io/api/metadata-block

The @downloadURL metadata key specifies the URL from which the script can be downloaded. This is used for automatic updates.

```javascript
// @downloadURL https://example.com/myscript.user.js
```

--------------------------------

### Specify Script Execution Time - @run-at

Source: https://violentmonkey.github.io/api/metadata-block

Use @run-at to control when your script runs. Options include document-start, document-body, document-end (default), and document-idle.

```javascript
// @run-at document-idle
```

--------------------------------

### GM_setClipboard

Source: https://violentmonkey.github.io/api/gm

Sets data to the system clipboard. Supports plain text by default, but can be extended to other MIME types.

```APIDOC
## GM_setClipboard

### Description
Sets data to system clipboard.

### Method Signature
```javascript
GM_setClipboard(data, type?)
```

### Parameters
* **data** : string - Required
  The data to be copied to system clipboard.
* **type** : string = 'text/plain' - Optional
  The MIME type of data to copy. Defaults to 'text/plain'.

### Examples
```javascript
GM_setClipboard('This text will be copied to the clipboard.')
GM_setClipboard('<html><body>Hello World</body></html>', 'text/html')
```
```

--------------------------------

### GM.setClipboard

Source: https://violentmonkey.github.io/api/gm

Sets the content of the system clipboard.

```APIDOC
## GM.setClipboard

### Description
Sets the content of the system clipboard.

### Method
`GM.setClipboard`
```

--------------------------------

### GM.registerMenuCommand

Source: https://violentmonkey.github.io/api/gm

Registers a command that will appear in the Violentmonkey menu.

```APIDOC
## GM.registerMenuCommand

### Description
Registers a command that will appear in the Violentmonkey menu.

### Method
`GM.registerMenuCommand`
```

--------------------------------

### Add @violentmonkey/shortcut via @require

Source: https://violentmonkey.github.io/guide/keyboard-shortcuts

Include the @violentmonkey/shortcut library in your userscript's meta block using `@require` to make it available.

```javascript
// ==UserScript==
// ...
// @require https://cdn.jsdelivr.net/npm/@violentmonkey/shortcut@1
// ==/UserScript==

```

--------------------------------

### Register a menu command with a shortcut

Source: https://violentmonkey.github.io/guide/keyboard-shortcuts

Associate a keyboard shortcut with a `GM_registerMenuCommand`. The shortcut is displayed in the menu item name using `VM.shortcut.reprShortcut`.

```javascript
const shortcut = 'c-g c-g';
const name = 'Good Game';
const handler = () => alert('Good Game!');

// Register menu command
const menuName = `${name} (${VM.shortcut.reprShortcut(shortcut)})`;
GM_registerMenuCommand(menuName, handler);

// Register shortcut
VM.shortcut.register(shortcut, handler);

```

--------------------------------

### Show Desktop Notification (Parameters)

Source: https://violentmonkey.github.io/api/gm

Displays a desktop notification using separate parameters, compatible with Greasemonkey.

```javascript
GM_notification(text, title, image, onclick)
```

--------------------------------

### Access VM.shortcut exports after @require

Source: https://violentmonkey.github.io/guide/keyboard-shortcuts

Once @violentmonkey/shortcut is included via `@require`, its exports can be accessed through the `VM.shortcut` object.

```javascript
const { register } = VM.shortcut;

```

--------------------------------

### Show Desktop Notification (Object Options)

Source: https://violentmonkey.github.io/api/gm

Displays a desktop notification using the browser's notifications API with detailed options.

```javascript
let control = GM_notification(options)
```

--------------------------------

### GM_download

Source: https://violentmonkey.github.io/api/gm

Downloads a URL to a local file. Supports downloading via an options object or separate parameters.

```APIDOC
## GM_download

_Since VM2.9.5_
Downloads a URL to a local file.

### Usage
1. Using an object:
```javascript
GM_download(options)
```

2. Using separate parameters:
```javascript
GM_download(url, name)
```

### Parameters
#### options (object)
* **url** (string) - The URL to download.
* **name** (string) - The filename to save to. Folders/subpaths aren’t supported yet.
* **headers?** (object)
* **timeout?** (number) - since VM2.9.5
* **context?** (any) - since VM2.13.4
* **user?** (string) - since VM2.13.4
* **password?** (string) - since VM2.13.4
* **anonymous?** (boolean = false) - since VM2.13.4
* **onabort?** (() => void) - since VM2.13.4
* **onerror?** (() => void)
* **onload?** (() => void)
* **onloadend?** (() => void) - since VM2.13.4
* **onloadstart?** (() => void) - since VM2.13.4
* **onprogress?** (() => void)
* **onreadystatechange?** (() => void) - since VM2.13.4
* **ontimeout?** (() => void)

#### url (string) - (Separate parameters usage)
The URL to download.

#### name (string) - (Separate parameters usage)
The filename to save to. Folders/subpaths aren’t supported yet.

### Event Handlers
* **onload** - The `onload` event handler is called after the data is downloaded from URL, before writing the file.
* Other event handlers like `onabort`, `onerror`, `onloadend`, `onloadstart`, `onprogress`, `onreadystatechange`, `ontimeout` are also supported and function similarly to `GM_xmlhttpRequest`.

### Returns
A control object with the following properties, same as GM_xmlhttpRequest:
* **abort** (() => void) - A function to abort the request.
```

--------------------------------

### GM.info

Source: https://violentmonkey.github.io/api/gm

Provides information about the current script.

```APIDOC
## GM.info

### Description
Provides information about the current script.

### Method
`GM.info`
```

--------------------------------

### Disable and re-enable all key bindings

Source: https://violentmonkey.github.io/guide/keyboard-shortcuts

Temporarily disable all registered keyboard shortcuts using `VM.shortcut.disable()` and re-enable them later with `VM.shortcut.enable()`.

```javascript
// Disable all key bindings temporarily
VM.shortcut.disable();

// Re-enable key bindings
VM.shortcut.enable();

```

--------------------------------

### Observe DOM Elements with jQuery and @violentmonkey/dom

Source: https://violentmonkey.github.io/guide/observing-dom

Integrate jQuery with VM.observe to manipulate dynamically created DOM elements using jQuery methods. Ensure both @violentmonkey/dom and jQuery are included as dependencies.

```javascript
VM.observe(document.body, () => {
  // Find the target node
  const $node = $('.profile');
 
  if ($node.length) {
    $node.prepend('<h1>Profile</h1>');
 
    // disconnect observer
    return true;
  }
});
```

--------------------------------

### GM_registerMenuCommand

Source: https://violentmonkey.github.io/api/gm

Registers a command in the Violentmonkey popup menu. It can optionally take an options object for advanced configurations like setting an ID, icon, title, or auto-close behavior.

```APIDOC
## GM_registerMenuCommand

### Description
Registers a command in Violentmonkey popup menu.

### Method Signature
```javascript
GM_registerMenuCommand(caption, onClick, options?)
```

### Parameters
* **caption** : string
  This text will be shown in the popup menu.
* **onClick** : (event) => void
  Callback function when the command is clicked.
  * **event** : [object Object] - since VM2.13.1
    The event that activated the command, providing details like `event.button`, `event.shiftKey`, `event.key`, etc.
* **options?** : object - since VM2.15.9
  Optional configuration for the menu command.
  * **id?** : string - since VM2.15.9
    Default: `caption` text since VM2.16.2. Default in 2.15.9-2.16.1: a randomly generated string.
  * **icon?** : string - since VM2.31.1
    URL of the icon to display.
  * **title?** : string
    A hint shown in the status bar when hovering the command.
  * **autoClose?** : boolean = true
    Whether to auto-close the popup after the user invokes the command.

### Returns
Returns the command’s `caption` since VM2.12.5 or `id` since VM2.15.9.

### Examples
```javascript
GM_registerMenuCommand('Text', onClick)
const id2 = GM_registerMenuCommand('Text2', onClick, { title: 'Two' })
const id3 = GM_registerMenuCommand('Text3', onClick, { autoClose: false })

// Example for in-place command change
const id = 'status';
const inplace = id === GM_registerMenuCommand('Enabled', onClick, { id });
if (inplace) {
  GM_registerMenuCommand('Disabled', onClick, { id, title: 'Status' });
} else {
  GM_unregisterMenuCommand('Enabled');
  GM_unregisterMenuCommand('Foo');
  GM_unregisterMenuCommand('Bar');
  GM_registerMenuCommand('Disabled', onClick);
  GM_registerMenuCommand('Foo', onClick2);
  GM_registerMenuCommand('Bar', onClick3);
}
```
```

--------------------------------

### Resource Declaration

Source: https://violentmonkey.github.io/api/metadata-block

The `@resource` key declares static resources that can be accessed using `GM_getResourceText` and `GM_getResourceURL`. It includes a resource name and its URL.

```javascript
// @resource logo https://my.cdn.com/logo.png

```

```javascript
// @resource text https://my.cdn.com/some-text.txt

```

--------------------------------

### Version Declaration

Source: https://violentmonkey.github.io/api/metadata-block

The `@version` key specifies the script's version, composed of parts joined by dots. If omitted, the script will not be updated automatically.

```javascript
// @version 1.0

```

```javascript
// @version 1.2a.3

```

--------------------------------

### Script Name with Localization

Source: https://violentmonkey.github.io/api/metadata-block

The `@name` key is required and can be localized. It defines the script's name shown in the script list and menus. Use `@name:localeCode` for localized names.

```javascript
// @name          Violentmonkey Script
// @name:zh-CN    暴力猴脚本

```

--------------------------------

### Enable Top-Level Await

Source: https://violentmonkey.github.io/api/metadata-block

The `// @top-level-await` metadata block enables the use of `await` at the top level of your script. This is useful for asynchronous operations that your script depends on, such as waiting for DOM elements or fetching network data. Avoid using it for importing dependencies that should always run; prefer `@require` and `@resource` instead. It cannot be used with `@unwrap`.

```javascript
// @top-level-await
```

--------------------------------

### Require External Script

Source: https://violentmonkey.github.io/api/metadata-block

The `@require` key allows specifying a URL to another script that must be executed before the current one. Local files are not permitted.

```javascript
// @require https://my.cdn.com/jquery.js

```

--------------------------------

### Observe DOM Elements with @violentmonkey/dom

Source: https://violentmonkey.github.io/guide/observing-dom

Use VM.observe to detect and manipulate dynamically created DOM elements. Return true from the callback to automatically disconnect the observer after the target node is found and processed.

```javascript
const disconnect = VM.observe(document.body, () => {
  // Find the target node
  const node = document.querySelector('.profile');
 
  if (node) {
    const h1 = document.createElement('h1');
    h1.textContent = 'Profile';
    node.prepend(h1);
 
    // disconnect observer
    return true;
  }
});

// You can also disconnect the observer explicitly when it's not used any more
disconnect();
```

--------------------------------

### GM.xmlHttpRequest Basic Usage

Source: https://violentmonkey.github.io/api/gm

Use this for basic cross-origin HTTP requests compatible with multiple userscript managers. The `onload` callback handles the response.

```javascript
// compatible with multiple userscript managers
GM.xmlHttpRequest({ url, onload: res => {/*....*/} });
```

--------------------------------

### Set System Clipboard Data

Source: https://violentmonkey.github.io/api/gm

Sets data to the system clipboard with an optional MIME type.

```javascript
GM_setClipboard(data, type)
```

--------------------------------

### GM_info

Source: https://violentmonkey.github.io/api/gm

Provides information about the script's environment, including platform, a unique script ID, and the Violent Monkey version.

```APIDOC
## GM_info

### Description
Provides information about the script's environment.

### Properties
- **platform** (string): The current platform.
- **getHighEntropyValues** (function): A function that returns high entropy values. It accepts an array of strings as hints and returns a Promise resolving to UADataValues.
- **uuid** (string): A unique ID of the script.
- **version** (string): The version of Violent Monkey.
```

--------------------------------

### GM.xmlHttpRequest Async/Await (VM2.18.3+)

Source: https://violentmonkey.github.io/api/gm

For Violentmonkey version 2.18.3 and later, and Tampermonkey, you can use `await` directly with GM.xmlHttpRequest for simplified asynchronous operations.

```javascript
// VM2.18.3+, TM
const res = await GM.xmlHttpRequest({ url });
```

--------------------------------

### GM.listValues

Source: https://violentmonkey.github.io/api/gm

Asynchronously lists all stored values.

```APIDOC
## GM.listValues

### Description
Asynchronously lists all stored values.

### Method
`GM.listValues` (async)
```

--------------------------------

### GM.xmlHttpRequest

Source: https://violentmonkey.github.io/api/gm

Makes an HTTP request.

```APIDOC
## GM.xmlHttpRequest

### Description
Makes an HTTP request. This function is asynchronous and returns a Promise in newer versions.

### Method
`GM.xmlHttpRequest` (async since VM2.18.3)

### Request Example
```javascript
// compatible with multiple userscript managers
GM.xmlHttpRequest({ url, onload: res => {/*....*/} });
```

### Response Example
```javascript
// compatible with multiple userscript managers
const res = await new Promise((resolve, reject) => {
  GM.xmlHttpRequest({ url, onload: resolve, onerror: reject });
});
```

### Response Example (VM2.18.3+, TM)
```javascript
// VM2.18.3+, TM
const res = await GM.xmlHttpRequest({ url });
```

### Response Example (Abort Control)
```javascript
// VM2.18.3+, TM
const control = GM.xmlHttpRequest({ url });
myButton.addEventListener('click', control.abort, { once: true });
const res = await control;
```
```

--------------------------------

### GM.setValues

Source: https://violentmonkey.github.io/api/gm

Asynchronously stores multiple key-value pairs.

```APIDOC
## GM.setValues

### Description
Asynchronously stores multiple key-value pairs.

### Method
`GM.setValues` (async)
```

--------------------------------

### GM.addStyle

Source: https://violentmonkey.github.io/api/gm

Adds CSS styles to the document.

```APIDOC
## GM.addStyle

### Description
Adds CSS styles to the document.

### Method
`GM.addStyle`
```

--------------------------------

### Specify Homepage URL - @homepageURL

Source: https://violentmonkey.github.io/api/metadata-block

The @homepageURL metadata key provides a link to the script's homepage, displayed via an icon in the user scripts list.

```javascript
// @homepageURL https://violentmonkey.github.io/
```

--------------------------------

### GM_addStyle

Source: https://violentmonkey.github.io/api/gm

Appends and returns a `<style>` element with the specified CSS.

```APIDOC
## GM_addStyle

### Description
Appends and returns a `<style>` element with the specified CSS.

### Method Signature
```javascript
let styleElement = GM_addStyle(css);
```

### Parameters
*   **css** : string
The CSS code to inject.

### Notes
Older versions of Violentmonkey (prior to 2.12.0) returned an imitation of Promise, which is still maintained for compatibility, so don’t be surprised if you see code like `GM_addStyle(css).then(el => { /* whatever */ });`
```

--------------------------------

### GM.xmlHttpRequest with Promises

Source: https://violentmonkey.github.io/api/gm

This snippet demonstrates how to use GM.xmlHttpRequest with Promises for cleaner asynchronous handling. It resolves with the response on success and rejects on error.

```javascript
// compatible with multiple userscript managers
const res = new Promise((resolve, reject) => {
  GM.xmlHttpRequest({ url, onload: resolve, onerror: reject });
});
```

--------------------------------

### GM_setValues

Source: https://violentmonkey.github.io/api/gm

Writes multiple values to the current script's storage. This is an efficient way to store multiple key/value pairs.

```APIDOC
## GM_setValues

### Description
Writes multiple values to current script’s storage.

### Method
```javascript
GM_setValues({ foo: 1, bar: [1, 2, 3] })
```

### Parameters
#### Arguments
- **data** (Object) - Required - Each `key:value` pair in the object will be stored individually. Must be _JSON serializable_.
```

--------------------------------

### GM.addElement

Source: https://violentmonkey.github.io/api/gm

Adds an element to the document.

```APIDOC
## GM.addElement

### Description
Adds an element to the document.

### Method
`GM.addElement`
```

--------------------------------

### Run Userscript on Entire SPA Site

Source: https://violentmonkey.github.io/api/matching

This @match rule ensures a userscript runs on all pages of a specific SPA site like YouTube.

```javascript
// @match *://www.youtube.com/*
```

--------------------------------

### GM_addElement

Source: https://violentmonkey.github.io/api/gm

Appends and returns an element with the specified attributes, useful for circumventing Content Security Policy restrictions.

```APIDOC
## GM_addElement

### Description
Appends and returns an element with the specified attributes with the primary purpose of circumventing a strict `Content-Security-Policy` that forbids adding inline code or style.

### Method Signature
```javascript
let element1 = GM_addElement(tagName, attributes);
let element2 = GM_addElement(parentNode, tagName, attributes);
```

### Parameters
*   **parentNode?** : Node | Element | ShadowRoot
    The parent node to which the new node will be appended. It can be inside ShadowDOM: `someElement.shadowRoot`. When omitted, it’ll be determined automatically:
    1. `document.head` (`<head>`) for `script`, `link`, `style`, `meta` tags.
    2. `document.body` (`<body>`) for other tags or when there’s no `<head>`.
    3. `document.documentElement` (`<html>` or an XML root node) otherwise.
*   **tagName** : string
A tag name like `'script'`.
*   **attributes?** : object
The keys are HTML attributes, not DOM properties, except `textContent` which sets DOM property `textContent`. The values are strings so if you want to assign a private function to `onload` you can do it after the element is created.

### Examples
```javascript
// using a private function in `onload`
let el = GM_addElement('script', { src: 'https://....' });
el.onload = () => console.log('loaded', el);
```
```javascript
// same as GM_addStyle('a { color:red }')
let el = GM_addElement('style', { textContent: 'a { color:red }' });
```
```javascript
// appending to an arbitrary node
let el = GM_addElement(parentElement.shadowRoot, 'iframe', { src: url });
```

### Notes
*   The element is returned immediately (synchronously) even with `GM.addElement`, no need for `.then()`, but you can use it if you want, just once though as it’s auto-removed to avoid recursion. The API is synchronous because Violentmonkey runs scripts only when the root element appears, so there’s always a node to serve as a parent.
*   Invalid arguments will raise an exception, which can be caught using `try {} catch (e) {}`, just like standard DOM API `document.createElement`.
```

--------------------------------

### Auto Inject into Page or Content Context

Source: https://violentmonkey.github.io/posts/inject-into-context

Use `@inject-into auto` to let Violentmonkey attempt injection into the page context first, falling back to the content context if blocked by CSP. This mode is suitable when direct access to page JavaScript objects is not required.

```javascript
// ==UserScript==
// ...
// @inject-into auto
// ==/UserScript==

// `@inject-into` can be set to `auto` if we don't need to access any JavaScript object from page context.

// Accessing JavaScript objects shared in both contexts
alert('The current page link is ' + window.location.href);

// Accessing DOM
document.body.style = 'background: orange';
```

--------------------------------

### Open URL in New Tab - GM_openInTab

Source: https://violentmonkey.github.io/api/gm

Opens a URL in a new tab. You can control whether the tab is active, pinned, or inserted next to the current tab. The function returns a tab control object with methods to manage the tab, such as closing it or handling its closure.

```javascript
let tabControl = GM_openInTab(url, options)
```

```javascript
let tabControl = GM_openInTab(url, openInBackground)
```

```javascript
let tabControl = GM_openInTab(url);
tabControl.onclose = () => console.log('tab is closed');
tabControl.close();
```

--------------------------------

### GM_listValues: List all keys in storage

Source: https://violentmonkey.github.io/api/gm

Returns an array containing the keys of all values currently stored for the script.

```javascript
let arrayOfKeys = GM_listValues()
```

--------------------------------

### GM.getValues

Source: https://violentmonkey.github.io/api/gm

Asynchronously retrieves multiple stored values.

```APIDOC
## GM.getValues

### Description
Asynchronously retrieves multiple stored values.

### Method
`GM.getValues` (async)
```

--------------------------------

### GM_addValueChangeListener: Add a storage change listener

Source: https://violentmonkey.github.io/api/gm

Adds a listener to observe changes in a specific storage key. It returns a listener ID that can be used to remove the listener later. The callback function receives the key name, old value, new value, and a boolean indicating if the change was remote.

```javascript
let listenerId = GM_addValueChangeListener(name, callback)
```

--------------------------------

### Script Injection Before Blob URLs (textContent)

Source: https://violentmonkey.github.io/posts/inject-scripts-with-blob-urls

In earlier versions, scripts were injected using `textContent`. This method is synchronous but can be blocked by CSP policies on certain Firefox versions.

```javascript
const s = document.createElement('script');
s.textContent = script;
document.body.appendChild(s);
document.body.removeChild(s);
```

--------------------------------

### GM_listValues

Source: https://violentmonkey.github.io/api/gm

Returns an array of keys of all available values within the current script's storage.

```APIDOC
## GM_listValues

### Description
Returns an array of keys of all available values within this script.

### Method
```javascript
let arrayOfKeys = GM_listValues()
```
```

--------------------------------

### Register Menu Command

Source: https://violentmonkey.github.io/api/gm

Registers a command in the Violent Monkey popup menu. Returns the command's caption or ID.

```javascript
GM_registerMenuCommand('Text', onClick)
const id2 = GM_registerMenuCommand('Text2', onClick, { title: 'Two' })
const id3 = GM_registerMenuCommand('Text3', onClick, { autoClose: false })
```

--------------------------------

### GM_getValues

Source: https://violentmonkey.github.io/api/gm

Retrieves multiple values for the current script from storage, either by an array of keys or an object mapping keys to default values.

```APIDOC
## GM_getValues

### Description
Retrieves multiple values for current script from storage.

### Method
1. **Using an array of keys:**
```javascript
let values = GM_getValues(['foo', 'bar'])
```
2. **Using an object:**
```javascript
let values = GM_getValues({ foo: 1, bar: [2] })
```

### Parameters
#### Arguments
- **keys** (string[]) - Required - An array of keys to retrieve.
- **data** (Object) - Required - An object where keys are the names to read from storage, and values are the defaults to be used if the key was not in storage.
```

--------------------------------

### SPA Navigation Event Listener

Source: https://violentmonkey.github.io/api/matching

Provides code to detect URL changes in Single Page Applications (SPAs) using `onUrlChange` and event listeners for `navigation` or `MutationObserver`.

```javascript
onUrlChange();

if (self.navigation) {
  navigation.addEventListener('navigatesuccess', onUrlChange);
} else {
  let u = location.href;
  new MutationObserver(() => u !== (u = location.href) && onUrlChange())
    .observe(document, {subtree: true, childList: true});
}

function onUrlChange() {
  if (!location.pathname.startsWith('/watch')) {
    // deactivate();
    return;
  }
  console.log('processing', location.href);
  // activate();
}
```

--------------------------------

### GM.setValue

Source: https://violentmonkey.github.io/api/gm

Asynchronously stores a key-value pair.

```APIDOC
## GM.setValue

### Description
Asynchronously stores a key-value pair.

### Method
`GM.setValue` (async)
```

--------------------------------

### Script Icon Declaration

Source: https://violentmonkey.github.io/api/metadata-block

The `@icon` key specifies an icon for the script, using a URL to the icon image.

```javascript
// @icon https://my.cdn.com/icon.png

```

--------------------------------

### GM_getValue

Source: https://violentmonkey.github.io/api/gm

Retrieves a value for the current script from storage. If the key does not exist, it returns the provided defaultValue.

```APIDOC
## GM_getValue

### Description
Retrieves a value for current script from storage.

### Method
```javascript
GM_getValue(key, defaultValue)
```

### Parameters
#### Arguments
- **key** (string) - Required - The name for the value to load.
- **defaultValue** (any) - Optional - The default value to return if no value exists in the storage.
```

--------------------------------

### GM_info Object

Source: https://violentmonkey.github.io/api/gm

The GM_info object provides access to various properties related to the current userscript and its execution environment. This includes information about the script's metadata, injection status, and platform details.

```APIDOC
## GM_info

An object that exposes information about the current userscript.

### Properties

*   **injectInto** : "auto" | "page" | "content"
    The injection mode of current script. See `@inject-into` for more information.
*   **isIncognito** : boolean
    True when this is an incognito profile (Chrome) or private mode (Firefox).
    @since VM2.15.4
*   **platform** : VMScriptGMInfoPlatform
    Unlike `navigator.userAgent`, which can be overriden by other extensions/userscripts or by devtools in device-emulation mode, `GM_info.platform` is more reliable as the data is obtained in the background page of Violentmonkey using a specialized extension API (`browser.runtime.getPlatformInfo` and `getBrowserInfo`).
    *   **arch** : "aarch64" | "arm" | "arm64" | "mips" | "mips64" | "ppc64" | "s390x" | "sparc64" | "x86-32" | "x86-64"
    *   **browserName** : string
    *   **browserVersion** : string
    *   **fullVersionList**?: Array<{
          * **brand** : string
          * **version** : string
        }> 
        A copy of `navigator.userAgentData.getHighEntropyValues()` from the background script of the extension, so it's not affected by devtools of the web page tab. Only present in browsers that implement this API (Chromium >= 90).
        @since VM2.27.0
    *   **mobile**?: boolean
        A copy of `navigator.userAgentData.mobile` from the background script of the extension, so it's not affected by devtools of the web page tab. Only present in browsers that implement this API (Chromium >= 90).
        @since VM2.27.0
    *   **os** : "mac" | "win" | "android" | "cros" | "linux" | "openbsd" | "fuchsia"
*   **script** : VMScriptGMInfoScriptMeta
    Contains structured fields from the Metadata Block.
    *   **antifeature**?: Array<string>
    *   **author**?: string
    *   **compatible**?: Array<string>
    *   **connect**?: Array<string>
    *   **description** : string
    *   **downloadURL**?: string
    *   **excludeMatches** : Array<string>
    *   **excludes** : Array<string>
    *   **grant** : Array<string>
        Empty is the same as `@grant none`
    *   **homepage**?: string
        Use homepageURL instead
    *   **homepageURL**?: string
    *   **icon**?: string
    *   **includes** : Array<string>
    *   **matches** : Array<string>
    *   **name** : string
    *   **namespace** : string
    *   **noframes**?: boolean
    *   **options** : {...}
        User options and overrides for the script
        @since VM2.31.1
        * **check_for_updates** : boolean
        * **inject_into** : "auto" | "page" | "content"
        * **noframes** : boolean
        * **override** : {...}
            * **merge_exclude_matches** : boolean
            Keep the script's `@exclude-match`
            * **merge_excludes** : boolean
            Keep the script's `@exclude`
            * **merge_includes** : boolean
            Keep the script's `@include`
            * **merge_matches** : boolean
            Keep the script's `@match`
            * **merge_tags** : boolean
            Keep the script's `@tag`
            @since VM2.35.2
            * **use_exclude_matches** : Array<string>
            User overridden `@exclude-match`
            * **use_excludes** : Array<string>
            User overridden `@exclude`
            * **use_includes** : Array<string>
            User overridden `@include`
            * **use_matches** : Array<string>
            User overridden `@match`
        * **run_at** : "document-start" | "document-body" | "document-end" | "document-idle"
        * **tags** : Array<string>
        User overridden `@tag`
        @since VM2.35.2
        * **user_modified** : number
        Last modification by the user; convertible as `new Date(user_modified)`
    *   **require** : Array<string>
    *   **resources** : Array<{
          * **name** : string
          * **url** : string
        }> 
    *   **runAt** : "" | "document-start" | "document-body" | "document-end" | "document-idle"
    *   **supportURL**?: string
    *   **tags**?: Array<string>
    @since VM2.37.0
    *   **unwrap**?: boolean
    *   **updateURL**?: string
    *   **version** : string
*   **scriptHandler** : string
    The name of userscript manager, which should be the string `Violentmonkey`.
*   **scriptMetaStr** : string
    The meta block of the script.
*   **scriptWillUpdate** : boolean
    Whether the script will be updated automatically.
*   **userAgent** : string
    A safe copy of `navigator.userAgent` from the content script of the extension, so it cannot be overridden by other extensions/userscripts, but unlike `GM_info.platform` it can be customized in devtools “device emulation” or “network conditions” for this tab.
    @since VM2.20.2
*   **userAgentData**?: {...}
    A safe copy of `navigator.userAgentData` from the content script of the extension, so it cannot be overridden by other extensions/userscripts, but unlike `GM_info.platform` it can be customized in devtools "device emulation" or "network conditions" for this tab.
    Only present if the browser actually implements it (currently Chromium-based 90+), because there's no reliable/official polyfill.
    Violentmonkey implements the official API, including getHighEntropyValues function to obtain the extra info asynchronously.
    @since VM2.20.2
    * **brands** : Array<{
          * **brand** : string
          * **version** : string
        }>
    * **mobile** : boolean

```

--------------------------------

### GM_getResourceText: Retrieve text resource from metadata

Source: https://violentmonkey.github.io/api/gm

Retrieves the text content of a resource defined in the script's metadata block.

```javascript
let text = GM_getResourceText(name)
```

--------------------------------

### Grant Specific APIs - @grant

Source: https://violentmonkey.github.io/api/metadata-block

Use @grant to explicitly allow access to special APIs. If no @grant is present, the script runs in a sandbox with limited access. '@grant none' disables the sandbox.

```javascript
// @grant none
```

```javascript
// @grant GM_getValue
// @grant GM_setValue
```

```javascript
// @grant GM.getValue
// @grant GM.setValue
```

```javascript
// @grant window.close
```

```javascript
// @grant window.focus
```

--------------------------------

### Append and Return Style Element - GM_addStyle

Source: https://violentmonkey.github.io/api/gm

Injects CSS into the page by appending a style element. Older versions returned a Promise-like object, which is maintained for compatibility.

```javascript
let styleElement = GM_addStyle(css);
```

--------------------------------

### Namespace Declaration

Source: https://violentmonkey.github.io/api/metadata-block

The `@namespace` key, combined with `@name`, uniquely identifies a userscript. It can be any string, often a homepage URL.

```javascript
// @namespace https://violentmonkey.github.io

```

--------------------------------

### GM_getResourceURL: Retrieve resource URL from metadata

Source: https://violentmonkey.github.io/api/gm

Retrieves a blob: or data: URL for a resource defined in the script's metadata block. An optional boolean parameter can specify whether to return a blob: URL (default) or a data: URL.

```javascript
let blobUrl = GM_getResourceURL(name);
```

```javascript
let blobOrDataUrl = GM_getResourceURL(name, isBlobUrl);
```

--------------------------------

### GM.notification

Source: https://violentmonkey.github.io/api/gm

Displays a notification to the user.

```APIDOC
## GM.notification

### Description
Displays a notification to the user.

### Method
`GM.notification`
```

--------------------------------

### Control Script Injection Context - @inject-into

Source: https://violentmonkey.github.io/api/metadata-block

Use @inject-into to decide whether the script runs in the page's context ('page') or content script context ('content'). 'auto' is the default.

```javascript
// @inject-into page
```

```javascript
// @inject-into content
```

```javascript
// @inject-into auto
```

--------------------------------

### GM_setValues: Set multiple values in storage

Source: https://violentmonkey.github.io/api/gm

Writes multiple key-value pairs to the script's storage efficiently. The values must be JSON serializable.

```javascript
GM_setValues({ foo: 1, bar: [1, 2, 3] })
```

--------------------------------

### Inject Script Without Wrapper - @unwrap

Source: https://violentmonkey.github.io/api/metadata-block

Use @unwrap to inject the script directly into the global scope without Violentmonkey's standard wrapper. This ignores @grant and supports @inject-into.

```javascript
// @unwrap
```
Tokens:
Raw