An Overview of the Web Storage API

Share this article

Web developers have long yearned for a way to store data long term. Cookies are an option, but they can only store 4KB of data.  Additionally, cookies are sent to the server with each HTTP request. This means that cookies, especially large ones, can consume considerable network bandwidth.  There have been other attempts to implement storage techniques, but for the most part they have been hacks.  Then, along came HTML5 and the Web Storage API to the rescue.

The Web Storage API defines two types of storage areas ― local storage and session storage.  Local storage is persistent data which remains until it is explicitly deleted, or until the browser’s cache is cleared.  According to the specification, browsers should allocate at least 5MB of local storage per domain.  The second storage type, session storage, is also persistent data, however the data is tied to a “top-level browsing context” (i.e. a browser tab or window).  Session data remains until it is either deleted or the browsing context is closed.  Session storage is particularly useful when a user is interacting with multiple instances of the same website.  In such a situation, using local storage could result in the different instances overwriting each others data.

The two types of storage areas are accessed through global objects named “localStorage” and “sessionStorage”.  Both storage areas implement the exact same API.  Data is stored as key/value pairs, and all data is stored in string form.  When adding data to storage, it is implicitly converted to a string.  However, when the string data is retrieved from storage it needs to be explicitly converted to the appropriate data type using functions such as parseInt().  When dealing with objects, the JSON.parse() and JSON.stringify() methods should be used for serialization and deserialization.

Detecting Storage Support

The Web Storage API, like many other HTML5 features, is not supported by all browsers.  To check if a browser supports storage, use the function shown below.  The function checks for the existence of the global “localStorage” object.  A similar function could be created to check for session storage, but it can be safely assumed that if one storage area exists, then so does the other.

function localStorageSupported() {
 try {
  return "localStorage" in window && window["localStorage"] !== null;
 } catch (e) {
  return false;

Storing Data

Data is added to storage using the setItem() method.  setItem() takes a key and value as arguments.  If the key does not already exist in storage, then the key/value pair is added.  If the key is already present, then the value is updated.  Several example setItem() usages are shown below.  The examples show how to add data of various types to local and session storage.  Notice that the “key” argument must always be a string, while the type of “value” can vary.

localStorage.setItem("key", "value");
sessionStorage.setItem("foo", 3.14);
localStorage.setItem("bar", true);
sessionStorage.setItem("baz", JSON.stringify(object));

Data can also be added to storage using object property assignment statements.  The previous setItem() examples have been rewritten below using assignment statements. Note that the assignment to “key” on the first line will fail silently.  This is because the storage areas have a built in function named key() that will be covered later.  For this reason, the API methods are the preferred way to access storage.

localStorage.key = "value"; // this fails silently = 3.14;
localStorage["bar"] = true;
sessionStorage["baz"] = JSON.stringify(object);

If a site attempts to store too much data, eventually the browser’s storage quota will be exceeded and an exception will be thrown.  To handle this case, try-catch blocks should be used when storing data.  An example of this is shown below.

try {
 localStorage.setItem("key", "value");
} catch (e) {
 alert("Exceeded Storage Quota!");

Reading Stored Data

To read data from storage, the getItem() method is used.  getItem() takes a lookup key as its sole argument.  If the key exists in storage, then the corresponding value is returned.  If the key does not exist, then null is returned.  The following examples use the getItem() method to retrieve the data stored in the setItem() examples.

var string = localStorage.getItem("key");
var number = sessionStorage.getItem("foo");
var boolean = localStorage.getItem("bar");
var object = JSON.parse(sessionStorage.getItem("baz"));

Stored data can also be accessed by reading properties of the “localStorage” and “sessionStorage” objects.  The previous getItem() examples have been rewritten below using object property syntax.

var string = localStorage.key;
var number =;
var boolean = localStorage["bar"];
var object = JSON.parse(sessionStorage["baz"]);

Iterating Over Stored Data

Often times, it is necessary to programmatically loop over all of the items in storage.  The loop’s upper bound is determined by the “length” property of the particular storage area.  The stored keys can be retrieved one at a time using the key() method.  key() takes a single integer parameter that acts as an index to the storage area.  An example of looping over each key/value pair in “localStorage” is shown below.  Of course, session storage can be processed in a similar fashion by substituting “sessionStorage” for “localStorage”.

for (var i = 0; i < localStorage.length; i++) {
 var key = localStorage.key(i);
 var value = localStorage.getItem(key);

 // do something with the key and value

Deleting Stored Data

When data is no longer needed, it should be explicitly removed.  This is especially true for local storage, as it will persist even after the browser is closed.  To delete individual key/value pairs from storage, the removeItem() method is used.  The removeItem() method takes the key to be deleted as its only parameter.  If the key is not present then nothing will happen.  Examples of the removeItem() method are shown below.


The delete operator can also be used to remove stored data.  The previous example is rewritten below using delete instead of removeItem().

delete localStorage.key;
delete localStorage["bar"];
delete sessionStorage["baz"];

While removeItem() is used to delete individual pieces of data, the clear() method is used to delete all stored data.  Usages of the clear() method are shown below.


The storage Event

A user can potentially have several instances of the same site open at any given time.  Changes made to a storage area in one instance need to be reflected in the other instances.  The Web Storage API accomplishes this synchronization using the “storage” event.  When a storage area is changed, a “storage” event is fired for any other tabs/windows that are sharing the storage area.  Note that a “storage” event is not fired for the tab/window that changes the storage area.

Storage areas can be changed by calls to setItem(), removeItem(), and clear().  However, not all calls to these methods actually change the storage area.  For example, calling clear() on an empty storage area or removeItem() on a key that does not exist will not change the storage area, and therefore will not fire an event.

The “storage” event object has several fields of interest which are described below.  Following the description of the fields is an example “storage” event handler.

  • “key” ― This field is the key argument of setItem() or removeItem(), or null when clear() caused the event to be fired.
  • “newValue” ― The “value” argument to setItem() is reflected in this field.  Calls to removeItem() and clear() cause this field to be null.
  • “oldValue” ― This field holds the key’s value prior to a call to setItem() or removeItem().  Calls to clear() cause this field to be null.
  • “url” ― The “url” field stores the address of the page whose storage area was affected.
  • “storageArea” ― The “storageArea” field corresponds to the local or session storage area that was changed.
window.addEventListener("storage", function(event) {
 var key = event.key;
 var newValue = event.newValue;
 var oldValue = event.oldValue;
 var url = event.url;
 var storageArea = event.storageArea;

 // handle the event

Example Page

The following code implements a sample page for manipulating local storage.  The page is also available online here.  The example covers the entire local storage API, including the “storage” event.  In order to see the “storage” event in action, the page must be open in at least two separate tabs/windows of the same browser.  The “storage” event will also only work if the page is served over HTTP (i.e. the file:// protocol will not work).

<!DOCTYPE html>
 <title>Web Storage Example</title>
 <meta charset="UTF-8" />
  "use strict";
  window.addEventListener("load", function(event) {
   var key = document.getElementById("key");
   var value = document.getElementById("value");
   var add = document.getElementById("add");
      var remove = document.getElementById("remove");
      var clear = document.getElementById("clear");
      var content = document.getElementById("content");

   add.addEventListener("click", function(event) {
        if (key.value !== "") {
     try {
           localStorage.setItem(key.value, value.value);
     } catch (e) {
      alert("Exceeded Storage Quota!");

      remove.addEventListener("click", function(event) {
        if (key.value !== "") {

      clear.addEventListener("click", function(event) {

      window.addEventListener("storage", function(event) {
        var k = event.key;
        var newValue = event.newValue;
        var oldValue = event.oldValue;
        var url = event.url;
        var storageArea = event.storageArea;

        alert("EVENT:n" + k + "n" + newValue + "n" + oldValue + "n" + url + "n" + storageArea);

      function refreshContents() {
        var str = "";

        for (var i = 0, len = localStorage.length; i < len; i++) {
          var k = localStorage.key(i);
          var v = localStorage.getItem(k);

          str += "'" + k + "' = '" + v + "'<br />";

    key.value = "";
    value.value = "";
        content.innerHTML = str;

  Key:  <input type="text" id="key" /><br />
  Value: <input type="text" id="value" /><br />
  <input type="button" id="add" value="Add to Storage" />&nbsp;
  <input type="button" id="remove" value="Remove from Storage" />&nbsp;
  <input type="button" id="clear" value="Clear Storage" /><br />
  Contents of Local Storage:<br />
  <span id="content"></span>

Things to Remember

  • Local storage persists until it is explicitly deleted or the browser’s cache is cleared.
  • Session storage persists until it is explicitly deleted or the browsing context is closed.
  • Data stored by one browser is not accessible by another browser.  For example, data stored by Chrome is not seen by Firefox.
  • Objects should be stored as JSON strings.
  • For security reasons, sensitive data should not be stored, especially in local storage.
  • Changes to a storage area cause a “storage” event to be fired.
  • As with many other HTML5 features, web storage is not yet implemented consistently.

Storage image via Shutterstock

Frequently Asked Questions about the Web Storage API

What is the difference between localStorage and sessionStorage in the Web Storage API?

Both localStorage and sessionStorage are part of the Web Storage API and allow you to store data in a user’s web browser. The main difference between the two lies in their lifespan and scope. localStorage data has no expiration time and persists even when the browser is closed and reopened, making it suitable for long-term data storage. On the other hand, sessionStorage data gets cleared when the page session ends, i.e., when the browser or tab is closed. This makes sessionStorage ideal for storing temporary data that is relevant to one session, like form data.

How can I access data stored in localStorage?

You can access data stored in localStorage using the getItem() method. This method takes one argument, which is the key of the data you want to retrieve. For example, if you have stored data with the key ‘username’, you can retrieve it using localStorage.getItem(‘username’). This will return the value associated with the ‘username’ key, or null if no such key exists.

Is there a limit to how much data I can store using the Web Storage API?

Yes, there is a limit to how much data you can store using the Web Storage API. Most modern browsers allow you to store up to 5MB of data per origin (i.e., per domain and protocol combination) for both localStorage and sessionStorage combined. However, this limit can vary between different browsers and can be lower in older browsers.

Is data stored using the Web Storage API secure?

Data stored using the Web Storage API is not inherently secure. It is stored in plain text and can be accessed by any script on your website. Therefore, it is not recommended to store sensitive information like passwords or credit card numbers using the Web Storage API. If you need to store such information, consider using secure methods like HTTPS and server-side sessions.

Can I store non-string data using the Web Storage API?

The Web Storage API only allows you to store string data. However, you can store non-string data by converting it to a string format using methods like JSON.stringify(). For example, if you have an array or object that you want to store, you can convert it to a JSON string before storing it, and then convert it back to its original format using JSON.parse() when retrieving it.

How can I delete data from localStorage?

You can delete data from localStorage using the removeItem() method. This method takes one argument, which is the key of the data you want to delete. For example, if you want to delete data with the key ‘username’, you can do so using localStorage.removeItem(‘username’). This will remove the data associated with the ‘username’ key.

Can users disable the Web Storage API?

Yes, users can disable the Web Storage API in their browser settings. If a user has disabled the Web Storage API, any attempts to store or retrieve data using it will result in an error. Therefore, it’s a good practice to always check whether the Web Storage API is available and enabled before using it.

How can I check if a certain key exists in localStorage?

You can check if a certain key exists in localStorage using the getItem() method. If the key exists, this method will return the value associated with the key. If the key does not exist, it will return null. Therefore, you can use a condition like if(localStorage.getItem(‘key’) !== null) to check if a key exists.

Can I store data in localStorage for a specific period of time?

By default, data stored in localStorage has no expiration time and persists until it is manually deleted. However, you can implement your own expiration mechanism by storing a timestamp along with the data and checking this timestamp whenever you retrieve the data.

Can I use the Web Storage API in all browsers?

The Web Storage API is supported in all modern browsers, including Chrome, Firefox, Safari, Edge, and Internet Explorer 8 and above. However, the exact features and storage limits can vary between different browsers and versions. Therefore, it’s a good practice to always check for browser compatibility when using the Web Storage API.

Colin IhrigColin Ihrig
View Author

Colin Ihrig is a software engineer working primarily with Node.js. Colin is the author of Pro Node.js for Developers, and co-author of Full Stack JavaScript Development with MEAN. Colin is a member of the Node.js Technical Steering Committee, and a hapi core team member. Colin received his Bachelor of Science in Engineering, and Master of Science in Computer Engineering from the University of Pittsburgh in 2005 and 2008, respectively.

HTML5 Dev Center
Share this article
Read Next
Get the freshest news and resources for developers, designers and digital creators in your inbox each week