Storage API

The storage system described by the Storage Standard, where site data is stored, usually consists of a single bucket for each origin.

In essence, every website has its own storage space into which its data gets placed. In some cases however, user agents may decide to store a single origin's data in multiple different buckets, for example when this origin is embedded in different third-party origins.

To learn more, see How browsers separate data from different websites?

Each site storage bucket has a mode that describes the data retention policy for that bucket. There are two modes:

"best-effort"

The user agent will try to retain the data contained in the bucket for as long as it can, but will not warn users if storage space runs low and it becomes necessary to clear the bucket in order to relieve the storage pressure.

"persistent"

The user agent will retain the data as long as possible, clearing all "best-effort" buckets before considering clearing a bucket marked "persistent". If it becomes necessary to consider clearing persistent buckets, the user agent will notify the user and provide a way to clear one or more persistent buckets as needed.

You can change an origin's storage bucket mode by using the navigator.storage.persist() method, which requires the "persistent-storage" user permission.

if (navigator.storage && navigator.storage.persist) {
  navigator.storage.persist().then((persistent) => {
    if (persistent) {
      console.log("Storage will not be cleared except by explicit user action");
    } else {
      console.log("Storage may be cleared by the UA under storage pressure.");
    }
  });
}

You can also use the navigator.storage.persisted() method to know whether an origin's storage is persistent or not:

if (navigator.storage && navigator.storage.persist) {
  navigator.storage.persisted().then((persistent) => {
    if (persistent) {
      console.log("Storage will not be cleared except by explicit user action");
    } else {
      console.log("Storage may be cleared by the UA under storage pressure.");
    }
  });
}

To learn more, see Does browser-stored data persist?.

The user agent determines, using whatever mechanism it chooses, the maximum amount of storage a given site can use. This maximum is the origin's quota. The amount of this space which is in use by the site is called its usage. Both of these values are estimates; there are several reasons why they're not precise:

• User agents are encouraged to obscure the exact size of the data used by a given origin, to prevent these values from being used for fingerprinting purposes.
• De-duplication, compression, and other methods to reduce the physical size of the stored data may be used.
• Quotas are conservative estimates of the space available for the origin's use, and should be less than the available space on the device to help prevent overruns.

To determine the estimated quota and usage values for a given origin, use the navigator.storage.estimate() method, which returns a promise that, when resolved, receives an object that contains these figures. For example:

navigator.storage.estimate().then((estimate) => {
  // estimate.quota is the estimated quota
  // estimate.usage is the estimated number of bytes used
});

For more information about how much data an origin can store, see How much data can be stored?.

Data eviction is the process by which a user agent deletes an origin's stored data. This can happen, for example, when the device used to store the data is running low on storage space.

When clearing the data stored by an origin, the origin's bucket is treated as a single entity. The entire data stored by this origin is cleared.

If a bucket is marked as "persistent", the contents won't be cleared by the user agent without either the data's origin itself or the user specifically doing so. This includes scenarios such as the user selecting a "Clear Caches" or "Clear Recent History" option. The user will be asked specifically for permission to remove persistent site storage buckets.

To learn more, see When is data evicted?.

• Using the Permissions API
• Storage for the web on web.dev
• Persistent storage on web.dev
• Chrome Web Storage and Quota Concepts