Storage API

BaselineWidely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since December 2021.

* Some parts of this feature may have varying levels of support.

Secure context: This feature is available only insecure contexts (HTTPS), in some or allsupporting browsers.

Note: This feature is available inWeb Workers.

TheStorage Standard defines a shared storage system designed to be used by all APIs and technologies that websites can use to store data in a user's browser.

The data stored for a website which is managed by the Storage Standard usually includesIndexedDB databases andCache API data, but may include other kind of site-accessible data such asWeb Storage API data.

The Storage API gives websites the ability to find out how much space they can use, how much they are already using, and even control whether or not they need to be alerted before theuser agent disposes of data in order to make room for other things.

This article gives an overview of the way user agents store and maintain websites' data. For more information about storage limits and eviction, seeBrowser storage quotas and eviction criteria.

This article also gives an overview of theStorageManager interface used to estimate available storage for a site.

Concepts and usage

Storage buckets

The storage system described by the Storage Standard, where site data is stored, usually consists of a singlebucket for eachorigin.

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, seeHow do browsers separate data from different websites?

Bucket modes

Each site storage bucket has amode 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 thenavigator.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 thenavigator.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, seeDoes browser-stored data persist?.

Quotas and usage estimates

The user agent determines, using whatever mechanism it chooses, the maximum amount of storage a given site can use. This maximum is the origin'squota. The amount of this space which is in use by the site is called itsusage. 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 forfingerprinting 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 thenavigator.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, seeHow much data can be stored?.

Data eviction

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, seeWhen is data evicted?.

Interfaces

StorageManager: Provides an interface for managing persistence permissions and estimating available storage.

Extensions to other interfaces

Navigator.storageRead only: Returns the singletonStorageManager object used for managing persistence permissions and estimating available storage on a site-by-site/app-by-app basis.
WorkerNavigator.storageRead only: Returns aStorageManager interface for managing persistence permissions and estimating available storage.