Tampermonkey® by Jan Biniok

Table of Contents

GM_setValue(key, value)

The GM_setValue allows a userscript to set the value of a specific key in the userscript's storage.

The GM_setValue function takes two parameters:

  • A string specifying the key for which the value should be set.
  • The value to be set for the key. Values (including nested object properties) can be null or of type "object", "string", "number", "undefined" or "boolean".

The GM_setValue function does not return any value. Instead, it sets the provided value for the specified key in the userscript's storage.

Here is an example of how GM_setValue and its async pendant GM.setValue might be used in a userscript:

GM_setValue("someKey", "someData");
await GM.setValue("otherKey", "otherData");

GM_getValue(key, defaultValue)

The GM_getValue function allows a userscript to retrieve the value of a specific key in the userscript's storage. It takes two parameters:

  • A string specifying the key for which the value should be retrieved.
  • A default value to be returned if the key does not exist in the userscript's storage. This default value can be of any type (string, number, object, etc.).

The GM_getValue function returns the value of the specified key from the userscript's storage, or the default value if the key does not exist.

Here is an example of how the GM_getValue function might be used in a userscript:

const someKey = GM_getValue("someKey", null);
const otherKey = await GM.getValue("otherKey", null);

In this example, the GM_getValue function is called with the key "someKey" and a default value of null. If the "someKey" key exists in the userscript's storage, its value will be returned and stored in the someKey variable. If the key does not exist, the default value of null will be returned and stored in the savedTab variable.

GM_deleteValue(key)

Deletes "key" from the userscript's storage.

GM_deleteValue("someKey");
await GM.deleteValue("otherKey");

GM_listValues()

The GM_listValues function returns a list of keys of all stored data.

const keys = GM_listValues();
const asyncKeys = await GM.listValues();

GM_setValues(values) v5.3+

The GM_setValues function allows a userscript to set multiple key-value pairs in the userscript's storage simultaneously.

The GM_setValues function takes one parameter:

  • An object where each key-value pair corresponds to a key and the value to be set for that key. Values (including nested object properties) can be null or of type "object", "string", "number", "undefined" or "boolean".

The GM_setValues function does not return any value. Instead, it sets the provided values for the specified keys in the userscript's storage.

Here is an example of how GM_setValues and its async counterpart GM.setValues might be used in a userscript:

GM_setValues({ foo: 1, bar: 2 });
await GM.setValues({ foo: 1, bar: 2 });

GM_getValues(keysOrDefaults) v5.3+

The GM_getValues function allows a userscript to retrieve the values of multiple keys in the userscript's storage. It can also provide default values if the keys do not exist.

The GM_getValues function takes one parameter:

  • Either an array of strings specifying the keys for which the values should be retrieved, or an object specifying the default values to be returned if the keys do not exist. This default values object can contain keys of any type (string, number, object, etc.).

The GM_getValues function returns an object containing the values of the specified keys from the userscript's storage, or the default values if the keys do not exist.

Here is an example of how the GM_getValues function might be used in a userscript:

const values = GM_getValues(['foo', 'bar']);
const asyncValues = await GM.getValues(['foo', 'bar']);

const defaultValues = GM_getValues({ foo: 1, bar: 2, baz: 3 });
const asyncDefaultValues = await GM.getValues({ foo: 1, bar: 2, baz: 3 });

In this example, the GM_getValues function is called with an array of keys or an object of default values. It returns an object with the values of the specified keys or the default values if the keys do not exist.

GM_deleteValues(keys) v5.3+

The GM_deleteValues function allows a userscript to delete multiple keys from the userscript's storage simultaneously.

The GM_deleteValues function takes one parameter:

  • An array of strings specifying the keys to be deleted from the userscript's storage.

The GM_deleteValues function does not return any value. Instead, it deletes the specified keys from the userscript's storage.

Here is an example of how GM_deleteValues and its async counterpart GM.deleteValues might be used in a userscript:

GM_deleteValues(['foo', 'bar']);
await GM.deleteValues(['foo', 'bar']);

GM_addValueChangeListener(key, (key, old_value, new_value, remote) => void)

The GM_addValueChangeListener function allows a userscript to add a listener for changes to the value of a specific key in the userscript's storage.

The function takes two parameters:

  • A string specifying the key for which changes should be monitored.
  • A callback function that will be called when the value of the key changes. The callback function should have the following signature:
      function(key, oldValue, newValue, remote) {
      // key is the key whose value has changed
      // oldValue is the previous value of the key
      // newValue is the new value of the key
      // remote is a boolean indicating whether the change originated from a different userscript instance
  }

The GM_addValueChangeListener function returns a "listenerId" value that can be used to remove the listener later using the GM_removeValueChangeListener function. The very same applies to GM.addValueChangeListener and GM.removeValueChangeListener with the only difference that both return a promise;

Here is an example of how the GM_addValueChangeListener function might be used in a userscript:

// Add a listener for changes to the "savedTab" key
var listenerId = GM_addValueChangeListener("savedTab", function(key, oldValue, newValue, remote) {
  // Print a message to the console when the value of the "savedTab" key changes
  console.log("The value of the '" + key + "' key has changed from '" + oldValue + "' to '" + newValue + "'");
});

GM_addValueChangeListener can be used by userscripts to communicate with other userscript instances at other tabs.

GM_removeValueChangeListener(listenerId)

GM_removeValueChangeListener and GM.removeValueChangeListener both get one argument called "listenerId" and remove the change listener with this ID.

Imprint Privacy Policy
▲