What Is the GM_setValue Function in Userscripts?

The GM_setValue function is a core API provided by userscript managers like Tampermonkey, Violentmonkey, and Greasemonkey that allows scripts to store data persistently across page reloads and different browser sessions. Unlike standard Web Storage options, GM_setValue binds saved data directly to the userscript itself rather than a specific web domain, enabling scripts to retain user preferences, application state, and cross-site data seamlessly.

How GM_setValue Works

Standard JavaScript variables reset every time a webpage reloads or navigates to a new URL. Browser storage APIs, such as localStorage, are tied to the domain of the active website, meaning data saved on one site cannot be accessed when navigating to another.

GM_setValue solves this by utilizing the storage layer of the userscript extension. Data saved via this function is isolated to your specific script, allowing it to persist across multiple tabs, different domains, and browser restarts.

Key Features

Cross-Domain Data Persistence: Retain information even when your userscript operates across multiple different websites.
Support for Rich Data Types: Modern implementations automatically serialize complex data structures like objects, arrays, booleans, and numbers without requiring manual string conversion.
Isolated Storage Environment: Prevents collision with the target website’s own localStorage key-value pairs.

Basic Syntax and Usage

To use GM_setValue, you must first declare it in your userscript’s metadata block using the @grant directive.

// ==UserScript==
// @name         Preference Saver Example
// @namespace    http://tampermonkey.net/
// @version      1.0
// @match        https://*/*
// @grant        GM_setValue
// @grant        GM_getValue
// ==UserScript==

// Storing a simple string value
GM_setValue("themeColor", "dark");

// Storing a complex JavaScript object
const userSettings = {
    fontSize: 16,
    notificationsEnabled: true,
    favoriteTags: ["javascript", "userscripts"]
};

GM_setValue("appSettings", userSettings);

Common Use Cases

1. Saving User Preferences

Userscripts frequently offer custom UI overlays, settings panels, or dark modes. GM_setValue ensures that custom configurations set by the user remain active every time they revisit the site.

2. Maintaining State Across Page Navigations

If a script performs multi-step automation—such as processing data across several paginated pages—GM_setValue can store current progress, counters, or queue items between page loads.

3. Caching External API Responses

To prevent hitting API rate limits or slowing down page load times, scripts can fetch external data once and cache the response using GM_setValue, updating it only after a set expiration period.

GM_setValue vs. Alternative Storage Methods

Storage Type	Domain Scope	Script Scope	Persistence	Data Types Supported
`GM_setValue`	Universal / Global	Isolated to your script	Persistent	Objects, Arrays, Strings, Numbers, Booleans
`localStorage`	Restricted to origin domain	Shared with target website	Persistent	Strings only (requires `JSON.stringify`)
`sessionStorage`	Restricted to origin domain	Shared with target website	Cleared on tab close	Strings only

Best Practices and Considerations

Always Include @grant: If you forget to add // @grant GM_setValue in the userscript header, calling the function will result in a runtime error.
Pair with GM_getValue: Use GM_getValue(key, defaultValue) to retrieve saved values reliably, providing a fallback default if the key does not yet exist.
Mind Storage Limits: While GM_setValue offers high storage limits compared to standard browser storage, storing massive files or large binary data directly in script storage can degrade browser extension performance.