Local Storage and Session Storage in JavaScript

Let's say you are creating a web app where users will be able to work either with text or media like images. You want to allow them to write some text that needs to be accessible even after a page refresh or a browser restart. Before the Web Storage API, you would have had to store the information on the back-end and reload it on the client side whenever needed. This is still the way to go if you want the information to be available across browsers or devices.

However, if the information that you want to preserve across page refreshes or browser restarts is meant to be accessible only on the same browser, the Web Storage API is a much more suitable tool.

There are two types of web storage implementations, called localStorage and sessionStorage. As you might have guessed from the names, sessionStorage preserves information for a single session, and localStorage preserves your data even after you restart the browser.

In this tutorial, you will learn all the basics of the Web Storage API, and you'll see how we can use local storage and session storage to our advantage.

Difference Between Local Storage and Session Storage

Before taking a deep dive into the API, let's learn the basic differences between local storage and session storage.

localStorage doesn't expire even on browser restart, while sessionStorage only lasts till a page refresh.
localStorage is shared across multiple tabs and windows that have the same origin. On the other hand, sessionStorage will be different for each tab that has loaded the same webpage.

A single webpage or document can have its own localStorage and sessionStorage object. However, they will be independent of each other.

Available Web Storage Methods and Properties

There are five methods available for both localStorage and sessionStorage.

You can use the setItem(key, value) method to store some information in the storage object as a key/value pair. If the key already exists, this method will update its value. Keep in mind that this method requires both key and value to be strings.

You can use the getItem(key) method to retrieve the information stored for a particular key. This method will return null if the passed key does not exist.

Let's say you want to remove some information from your localStorage or sessionStorage. In this case, you can use the removeItem(key) method and pass the relevant key name in order to remove a key and its value from the storage.

Instead of removing keys from your storage one at a time, you can also use the clear() method to clear all the keys at once.

There is also a key(index) method that accepts an integer as the key index and gives you back the name of the key at that particular index. The important thing to remember here is that the order of keys is defined by the user-agent.

Finally, there is a length property that you can use to get the number of data items stored in a given storage object.

You can use the length property in combination with the key() method and the getItem() method to access the values of all keys in your localStorage or sessionStorage.

Here are some examples of using all these methods:

/* Save some key-value pairs */
localStorage.setItem("artist", "Monty Shokeen");
localStorage.setItem("website", "tutsplus.com");
localStorage.setItem("font", "Righteous");
localStorage.setItem("stroke_width", "4");
localStorage.setItem("color", "#FF5722");

/* Access stored values */
console.log(localStorage.getItem("color"));
// Outputs: #FF5722

console.log(localStorage.getItem("stroke_width"));
// Outputs: 4

/* Iterate over keys */
for (let i = 0; i < localStorage.length; i++) {
  console.log(`${localStorage.key(i)} : ${localStorage.getItem(localStorage.key(i))}`);
}
/*
stroke_width : 4
font : Righteous
website : tutsplus.com
color : #FF5722
artist : Monty Shokeen
*/

/* Removing keys from storage */
localStorage.removeItem("website"); 
localStorage.getItem("website"); 
// Outputs: null

Practical Application of Local Storage

Let's do something practical with all the knowledge we have gained. We will create a simple drawing application where users will be able to save their data in the local storage for retrieval in the future.

Our drawing application is going to be very simple. We will have a canvas where users will be able to draw concentric circles of random radius. The minimum and maximum value of the radius will be determined by input fields filled by them. We will also have a button to clear the canvas once we have drawn too many circles. Here is our markup:

<canvas id="canvas" width="810" height="400"></canvas>
<form>
  <label for="min-rad">Min. Radius</label>
  <input type="number" name="min-rad" id="min-rad" min="4"></input>
  <br>
  <label for="max-rad">Max. Radius</label>
  <input type="number" name="max-rad" id="max-rad" min="20"></input>
  <br>
  <button type="button" id="clear">Clear Canvas</button>
</form>

We will be storing three pieces of information in our local storage: the minimum radius, the maximum radius, and the state of the canvas. Remember that local storage can only store information as strings. The value of input fields can be automatically converted to strings. However, we will need to use the toDataURL() method to get the state of our canvas as a string. This method will give us back a string that contains the requested data URL.

We will attach event listeners to all the elements on the webpage: a mousedown event listener for the canvas, a change event listener for the input elements, and a click event listener for the buttons. Let's start with some initialization code and the event listeners for the form fields.

const canvas = document.getElementById("canvas");
const ctx = canvas.getContext("2d");

const minElem = document.querySelector("input#min-rad");
const maxElem = document.querySelector("input#max-rad");
const clearBtn = document.querySelector("button#clear");

let min_radius = 10;
let max_radius = 30;

minElem.addEventListener("change", function(event) {
  min_radius = parseInt(event.target.value);
  localStorage.setItem("min-radius", min_radius);
});

maxElem.addEventListener("change", function(event) {
  max_radius = parseInt(event.target.value);
  localStorage.setItem("max-radius", max_radius);
});

clearBtn.addEventListener("click", function(event) {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  
  let image_data = canvas.toDataURL();
  localStorage.setItem("image-data", image_data);
});

By default, we keep the minimum and maximum radius values set to 10 and 30 pixels respectively. The change event listener for the minimum and maximum radius input fields will parse the value of inputs and then store those values in local storage.

Within the click event listener callback for our button, we first cleared the canvas and then saved this cleared state to our local storage using the toDataUrl() method.

Here is the code that listens to the mousedown event on our canvas.

canvas.addEventListener('mousedown', function(event) {
    const canvas_rect = event.target.getBoundingClientRect();
    const pos_x = event.clientX - canvas_rect.left;
    const pos_y = event.clientY - canvas_rect.top;
  
    for(let i = 0; i < 10; i++) {
      let radius = min_radius + Math.floor(Math.random()*(max_radius - min_radius));
      ctx.beginPath();
      ctx.arc(pos_x, pos_y, radius, 0, 2 * Math.PI);
      ctx.stroke();
    }
  
    let image_data = canvas.toDataURL();
    localStorage.setItem("image-data", image_data);
});

Let's break it down. We begin by calculating the exact position where users clicked on the canvas. This is determined by subtracting the value of the left property of the bounding rectangle of the canvas from the x coordinate of the clicked position. We do the same thing to get the vertical position of the click.

After that, we create a for loop to draw ten concentric circles on the canvas. The radius is set to a random value subject to the minimum and maximum constraints. Finally, just like the click listener for the button, we save the canvas state in our local storage. This happens with each click so that we can stay up-to-date with the latest canvas state.

The only thing left for us to do now is to restore the values from the local storage to be used on reloads or restarts. We do this with the following code:

window.addEventListener("DOMContentLoaded", (event) => {
  if (localStorage.getItem("image-data")) {
    var img = new Image();
    img.onload = function () {
      ctx.drawImage(img, 0, 0);
    };
    img.src = localStorage.getItem("image-data");
  }

  if (localStorage.getItem("min-radius")) {
    min_radius = parseInt(localStorage.getItem("min-radius"));
  }

  if (localStorage.getItem("max-radius")) {
    max_radius = parseInt(localStorage.getItem("max-radius"));
  }

  minElem.value = min_radius;
  maxElem.value = max_radius;
});

The most complicated section here is the restoration of image data from the local storage to the canvas. We do this by first creating a new instance of HTMLImageElement and then listening to its onload event in order to draw the loaded image on the canvas.

The following CodePen demo will show you our drawing application in action. Try clicking on the canvas to draw some circles or set the radius to values you like first.

Right now, we are using localStorage in our tutorial, which means that our data will be safe even if the browser restarts. You can try replacing it with sessionStorage to preserve the information only during page refreshes.

Final Thoughts

In this tutorial, we covered the basics of localStorage and sessionStorage in JavaScript. You should now be able to store and retrieve information in the browser's storage using the Web Storage API. This API has a lot of applications as we saw while creating our drawing app here. You can also use it to implement content-saving functionality in a local text editor.