Privileged APIs

Violentmonkey APIs are derived from those in Greasemonkey v3, and most of them work the same way, GM.* Greasemonkey v4-compatible aliases were added in VM2.12.0.

unsafeWindow

It’s the original window object of the webpage that allows reading or modifying global variables, necessary when the script is sandboxed, because its window becomes a wrapper that confines modifications like window.foo = 123 to this script’s scope.

Sandboxing is enabled by default and disabled only if @grant none is specified, just like in Tampermonkey. Note that in older versions of Violentmonkey (before v2.32) sandboxing was also disabled when there were no @grant keys.

GM_*

GM_* are a group of special APIs provided by Violentmonkey.

GM_info

GM_info: {...}

An object that exposes information about the current userscript.

  • downloadMode: "native" | "browser"

    GM_download internal implementation: native - the classic a element's download attribute, used by default. browser - the browser API used if the user enabled it in the extension's options.

    @since VM2.45.2

  • 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: {...}

    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" | "ppc64" | "s390x" | "sparc64" | "x86-32" | "x86-64" | "arm64" | "mips" | "mips64"

    • browserName: string

    • browserVersion: string

    • fullVersionList?: Array<{...}>

      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

      • brand: string

      • version: string

    • 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: {...}

    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

    • platform: string

    • getHighEntropyValues: (hints: Array<string>) => Promise<UADataValues>

  • uuid: string

    A unique ID of the script.

  • version: string

    Version of Violentmonkey.

GM_cookie: {...}

@since VM2.35.1

  • delete: (opts: {...} | {...},
    callback?: (error?: string) => any,
    ) => void

  • list: (opts: {...} | Parameters<typeof chrome.cookies.getAll>[0],
    callback?: (cookies?: {...} | {...}, error?: string) => any,
    ) => void

    httpOnly cookies are listed only when the HTTP-only option is enabled for the script and globally in the extension

  • set: (opts: {...} | Parameters<typeof chrome.cookies.set>[0],
    callback?: (error?: string) => any,
    ) => void

    httpOnly cookies are allowed only when the HTTP-only option is enabled for the script and globally in the extension

GM_getValue

Retrieves a value for current script from storage.

let value = GM_getValue(key, defaultValue)
  • key: string

    The name for value to load.

  • defaultValue: any

    The default value to return if no value exists in the storage.

GM_getValues

Since VM2.19.1

Retrieves multiple values for current script from storage.

  1. Using an array of keys.

    let values = GM_getValues(['foo', 'bar'])
    Keys in storageResult
    foo, bar{ foo: 123, bar: [1, 2, 3] }
    foo{ foo: 123 }

  2. Using an object.

    Each key is a name to read from storage, the value is the default to be used in the result if the key was not in storage.

    let values = GM_getValues({ foo: 1, bar: [2] })
    Keys in storageResult
    foo, bar{ foo: 123, bar: [1, 2, 3] }
    foo{ foo: 123, bar: [2] }

GM_setValue

Sets a key / value pair for current script to storage.

GM_setValue(key, value)
  • key: string

    The unique name for value within this script.

  • value: any

    The value to be stored, which must be JSON serializable (string, number, boolean, null, or an array/object consisting of these types) so for example you can’t store DOM elements or objects with cyclic dependencies.

GM_setValues

Since VM2.19.1

Writes multiple values to current script’s storage.

GM_setValues({ foo: 1, bar: [1, 2, 3] })
  • data: Object

    Each key:value pair in the object will be stored individually, so the example above is basically a more efficient version of GM_setValue('foo', 1); GM_setValue('bar', [1, 2, 3]);

    Must be JSON serializable (see GM_setValue).

GM_deleteValue

Deletes an existing key / value pair for current script from storage.

GM_deleteValue(key)
  • key: string

    The unique name for value within this script.

GM_deleteValues

Since VM2.19.1

Deletes values with the specified keys in current script’s storage.

GM_deleteValues(['foo', 'bar'])
  • keys: string[]

    Array of keys to delete.

GM_listValues

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

let arrayOfKeys = GM_listValues()

GM_addValueChangeListener

Adds a change listener to the storage and returns the listener ID.

let listenerId = GM_addValueChangeListener(name, callback)
  • name: string

    The name of the observed variable

  • callback: (name, oldValue, newValue, remote) => void
    • name: string

      The name of the observed variable

    • oldValue: any

      The old value of the observed variable (undefined if it was created)

    • newValue: any

      The new value of the observed variable (undefined if it was deleted)

    • remote: boolean

      true if modified by the userscript instance of another tab or false for this script instance. Can be used by scripts of different browser tabs to communicate with each other.

GM_removeValueChangeListener

Removes a change listener by its ID.

GM_removeValueChangeListener(listenerId)
  • listenerId: string

GM_getResourceText

Retrieves a text resource from the metadata block.

let text = GM_getResourceText(name)

GM_getResourceURL

Retrieves a blob: or data: URL of a resource from the metadata block.

let blobUrl = GM_getResourceURL(name);
let blobOrDataUrl = GM_getResourceURL(name, isBlobUrl);
  • name: string

    Name of a resource defined in the metadata block.

  • isBlobUrl: boolean = true- since VM2.13.1

    • true returns a blob: URL. It’s short and cacheable, so it’s good for reusing in multiple DOM elements.

    • false returns a data: URL. It’s long so reusing it in DOM may be less performant due to the lack of caching, but it’s particularly handy for direct synchronous decoding of the data on sites that forbid fetching blob: in their CSP.