Web Storage is what the JavaScript API browsers provide for storing data locally and securely within a user’s browser.
Session and local storage are the two main types of web storage. They are similar to regular properties objects, but they persist (do not disappear) when the webpage reloads.
This article aims to show you exactly how the two storage objects work in JavaScript. We will also use a To-Do list exercise to practice using web storage in a web app project.
Table of Contents
- What is the Session Storage Object?
- What is the Local Storage Object?
- How to Access the Session and Local Storage Objects
- What are Web Storage’s Built-In Interfaces?
- Time to Practice with Web Storage 🤸♂️🏋️♀️
- How Did You Go About Solving the Web Storage Exercise?
- How to prevent the Session Storage pane’s To-Do items from disappearing on page reload
- How to prevent the Local Storage pane’s To-Do items from disappearing on page reload or reopen
- How to auto-display the Session section’s previously added tasks on page reload
- How to auto-display the Local section’s previously added tasks on page reload or reopen
- How to check the total items in the browser’s session storage
- How to display the local storage’s zeroth index item’s name
- How to empty the browser’s session storage
- How to Continue Practicing with Web Storage 🧗♀️🚀
- Web Storage vs. Cookies: What is the Difference?
- Wrapping up
Without further ado, let’s discuss session storage.
What is the Session Storage Object?
The session storage object (window.sessionStorage
) stores data that persists for only one session of an opened tab.
In other words, whatever gets stored in the window.sessionStorage
object will not disappear on a reload of the web page. Instead, the computer will delete the stored data only when users close the browser tab or window.
Note the following:
- The data stored inside the session storage is per-origin and per-instance. In other words,
http://freecodecamp.com
’ssessionStorage
object is different fromhttps://freecodecamp.com
’ssessionStorage
object because the two origins use different schemes (http
andhttps
). - Per-instance means per-window or per-tab. In other words, the
sessionStorage
object’s lifespan expires once users close the instance (window or tab). - Browsers create a unique page session for each new tab or window. Therefore, users can run multiple instances of an app without interfering with each instance’s session storage. (Note: Cookies do not have good support for running multiple instances of the same app. Such an attempt can cause errors such as double entry of bookings.)
- Session storage is a property of the global
Window
object. SosessionStorage.setItem()
is equivalent towindow.sessionStorage.setItem()
.
What is the Local Storage Object?
The local storage object (window.localStorage
) stores data that persists even when users close their browser tab (or window).
In other words, whatever gets stored in the window.localStorage
object will not disappear during a reload or reopening of the web page or when users close their browsers. Those data have no expiration time. Browsers never clear them automatically.
The computer will delete the window.localStorage
object’s content in the following instances only:
- When the content gets cleared through JavaScript
- When the browser’s cache gets cleared
Note the following:
- The
window.localStorage
object’s storage limit is larger than thewindow.sessionStorage
. - The data stored inside the local storage is per-origin. In other words,
http://freecodecamp.com
’slocalStorage
object is different fromhttps://freecodecamp.com
’slocalStorage
object because the two origins use different schemes (http
andhttps
). - There are inconsistencies with how browsers handle the local storage of documents not served from a web server (for instance, pages with a
file:
URL scheme). Therefore, thelocalStorage
object may behave differently among browsers when used with non-HTTP URLs, such asfile:///document/on/users/local/system.html
. - Local storage is a property of the global
Window
object. Therefore,localStorage.setItem()
is equivalent towindow.localStorage.setItem()
.
How to Access the Session and Local Storage Objects
You can access the two web storages by:
- Using the same technique as you'd use for accessing regular JavaScript objects
- Using web storage’s built-in interfaces
For instance, consider the snippet below:
sessionStorage.bestColor = "Green";
sessionStorage["bestColor"] = "Green";
sessionStorage.setItem("bestColor", "Green");
The three statements above do the same thing—they set bestColor
’s value. But the third line is recommended because it uses web storage’s setItem()
method.
Tip: you should prefer using the web storage’s built-in interfaces to avoid the pitfalls of using objects as key/value stores.
Let’s discuss more on the web storage’s built-in interfaces below.
What are Web Storage’s Built-In Interfaces?
The web storage built-in interfaces are the recommended tools for reading and manipulating a browser’s sessionStorage
and localStorage
objects.
The six (6) built-in interfaces are:
setItem()
key()
getItem()
length
removeItem()
clear()
Let’s discuss each one now.
What is web storage’s setItem()
method?
The setItem()
method stores its key
and value
arguments inside the specified web storage object.
Syntax of the setItem()
method
setItem()
accepts two required arguments. Here is the syntax:
webStorageObject.setItem(key, value);
webStorageObject
represents the storage object (localStorage
orsessionStorage
) you wish to manipulate.key
is the first argument accepted bysetItem()
. It is a required string argument representing the name of the web storage property you want to create or update.value
is the second argument accepted bysetItem()
. It is a required string argument specifying the value of thekey
you are creating or updating.
Note:
- The
key
andvalue
arguments are always strings. - Suppose you provide an integer as a
key
orvalue
. In that case, browsers will convert them to strings automatically. setItem()
may display an error message if the storage object is full.
Example 1: How to store data in the session storage object
- Invoke
sessionStorage
’ssetItem()
method. - Provide the name and value of the data you wish to store.
// Store color: "Pink" inside the browser's session storage object:
sessionStorage.setItem("color", "Pink");
// Log the session storage object to the console:
console.log(sessionStorage);
// The invocation above will return:
{color: "Pink"}
Note: Your browser’s session storage may contain additional data if it already uses the storage object to store information.
Example 2: How to store data in the local storage object
- Invoke
localStorage
’ssetItem()
method. - Provide the name and value of the data you wish to store.
// Store color: "Pink" inside the browser's local storage object:
localStorage.setItem("color", "Pink");
// Log the local storage object to the console:
console.log(localStorage);
// The invocation above will return:
{color: "Pink"}
Note:
- Your browser’s local storage may contain additional data if it already uses the storage object to store information.
- It is best to serialize objects before storing them in local or session storage. Otherwise, the computer will store the object as
"[object Object]"
.
Example 3: Browsers use "[object Object]"
for non-serialized objects in the web storage
// Store myBio object inside the browser's session storage object:
sessionStorage.setItem("myBio", { name: "Oluwatobi" });
// Log the session storage object to the console:
console.log(sessionStorage);
// The invocation above will return:
{myBio: "[object Object]", length: 1}
You can see that the computer stored the object as "[object Object]"
because we did not serialize it.
Example 4: How to store serialized objects in the web storage
// Store myBio object inside the browser's session storage object:
sessionStorage.setItem("myBio", JSON.stringify({ name: "Oluwatobi" }));
// Log the session storage object to the console:
console.log(sessionStorage);
// The invocation above will return:
{myBio: '{"name":"Oluwatobi"}', length: 1}
We used JSON.stringify()
to convert the object to JSON before storing it in the web storage.
Tip: Learn how to convert JSON to JavaScript objects.
What is web storage’s key()
method?
The key()
method retrieves a specified web storage item’s name (key).
Syntax of the key()
method
key()
accepts one required argument. Here is the syntax:
webStorageObject.key(index);
webStorageObject
represents the storage object (localStorage
orsessionStorage
) whose key you wish to get.index
is a required argument. It is an integer specifying the index of the item whose key you want to get.
Example 1: How to get the name of an item in the session storage object
- Invoke
sessionStorage
’skey()
method. - Provide the index of the item whose name you wish to get.
// Store carColor: "Pink" inside the browser's session storage object:
sessionStorage.setItem("carColor", "Pink");
// Store pcColor: "Yellow" inside the session storage object:
sessionStorage.setItem("pcColor", "Yellow");
// Store laptopColor: "White" inside the session storage object:
sessionStorage.setItem("laptopColor", "White");
// Get the name of the item at index 1:
sessionStorage.key(1);
Important: The user-agent defines the order of items in the session storage. In other words, key()
’s output may vary based on how the user-agent orders the web storage’s items. So you shouldn't rely on key()
to return a constant value.
Example 2: How to get the name of an item in the local storage object
- Invoke
localStorage
’skey()
method. - Provide the index of the item whose name you wish to get.
// Store carColor: "Pink" inside the browser's local storage object:
localStorage.setItem("carColor", "Pink");
// Store pcColor: "Yellow" inside the local storage object:
localStorage.setItem("pcColor", "Yellow");
// Store laptopColor: "White" inside the local storage object:
localStorage.setItem("laptopColor", "White");
// Get the name of the item at index 1:
localStorage.key(1);
Important: The user-agent defines the order of items in the local storage. In other words, key()
’s output may vary based on how the user-agent orders the web storage’s items. So you shouldn't rely on key()
to return a constant value.
What is web storage’s getItem()
method?
The getItem()
method retrieves the value of a specified web storage item.
Syntax of the getItem()
method
getItem()
accepts one required argument. Here is the syntax:
webStorageObject.getItem(key);
webStorageObject
represents the storage object (localStorage
orsessionStorage
) whose item you wish to get.key
is a required argument. It is a string specifying the name of the web storage property whose value you want to get.
Example 1: How to get data from the session storage object
- Invoke
sessionStorage
’sgetItem()
method. - Provide the name of the data you wish to get.
// Store color: "Pink" inside the browser's session storage object:
sessionStorage.setItem("color", "Pink");
// Get color's value from the session storage:
sessionStorage.getItem("color");
// The invocation above will return:
"Pink"
Example 2: How to get data from the local storage object
- Invoke
localStorage
’sgetItem()
method. - Provide the name of the data you wish to get.
// Store color: "Pink" inside the browser's local storage object:
localStorage.setItem("color", "Pink");
// Get color's value from the local storage:
localStorage.getItem("color");
// The invocation above will return:
"Pink"
Note: The getItem()
method will return null
if its argument does not exist in the specified web storage.
What is web storage’s length
property?
The length
property returns the number of properties in the specified web storage.
Syntax of the length
property
Here is length
’s syntax:
webStorageObject.length;
webStorageObject
represents the storage object (localStorage
or sessionStorage
) whose length you wish to verify.
Example 1: How to verify the number of items in the session storage object
Invoke sessionStorage
’s length
property.
// Store carColor: "Pink" inside the browser's session storage object:
sessionStorage.setItem("carColor", "Pink");
// Store pcColor: "Yellow" inside the session storage object:
sessionStorage.setItem("pcColor", "Yellow");
// Store laptopColor: "White" inside the session storage object:
sessionStorage.setItem("laptopColor", "White");
// Verify the number of items in the session storage:
sessionStorage.length;
// The invocation above may return:
3
Note: Your sessionStorage.length
invocation may return a value greater than 3
if your browser’s session storage already contains some stored information.
Example 2: How to verify the number of items in the local storage object
Invoke localStorage
’s length
property.
// Store carColor: "Pink" inside the browser's local storage object:
localStorage.setItem("carColor", "Pink");
// Store pcColor: "Yellow" inside the local storage object:
localStorage.setItem("pcColor", "Yellow");
// Store laptopColor: "White" inside the local storage object:
localStorage.setItem("laptopColor", "White");
// Verify the number of items in the local storage:
localStorage.length;
// The invocation above may return:
3
Note: Your localStorage.length
invocation may return a value greater than 3
if your browser's local storage already contains some stored information.
What is web storage’s removeItem()
method?
The removeItem()
method removes a property from the specified web storage.
Syntax of the removeItem()
Method
removeItem()
accepts one required argument. Here is the syntax:
webStorageObject.removeItem(key);
webStorageObject
represents the storage object (localStorage
orsessionStorage
) whose item you wish to remove.key
is a required argument. It is a string specifying the name of the web storage property you want to remove.
Example 1: How to remove data from the session storage object
- Invoke
sessionStorage
’sremoveItem()
method. - Provide the name of the data you wish to remove.
// Store carColor: "Pink" inside the browser's session storage object:
sessionStorage.setItem("carColor", "Pink");
// Store pcColor: "Yellow" inside the session storage object:
sessionStorage.setItem("pcColor", "Yellow");
// Store laptopColor: "White" inside the session storage object:
sessionStorage.setItem("laptopColor", "White");
// Remove the pcColor item from the session storage:
sessionStorage.removeItem("pcColor");
// Confirm whether the pcColor item still exists in the session storage:
sessionStorage.getItem("pcColor");
// The invocation above will return:
null
Note: The removeItem()
method will do nothing if its argument does not exist in the session storage.
Example 2: How to remove data from the local storage object
- Invoke
localStorage
’sremoveItem()
method. - Provide the name of the data you wish to remove.
// Store carColor: "Pink" inside the browser's local storage object:
localStorage.setItem("carColor", "Pink");
// Store pcColor: "Yellow" inside the local storage object:
localStorage.setItem("pcColor", "Yellow");
// Store laptopColor: "White" inside the local storage object:
localStorage.setItem("laptopColor", "White");
// Remove the pcColor item from the local storage:
localStorage.removeItem("pcColor");
// Confirm whether the pcColor item still exists in the local storage:
localStorage.getItem("pcColor");
// The invocation above will return:
null
Note: The removeItem()
method will do nothing if its argument does not exist in the local storage.
What is web storage’s clear()
method?
The clear()
method clears (deletes) all the items in the specified web storage.
Syntax of the clear()
Method
clear()
accepts no argument. Here is the syntax:
webStorageObject.clear();
webStorageObject
represents the storage object (localStorage
or sessionStorage
) whose items you wish to clear.
Example 1: How to clear all items from the session storage object
Invoke sessionStorage
’s clear()
method.
// Store carColor: "Pink" inside the browser's session storage object:
sessionStorage.setItem("carColor", "Pink");
// Store pcColor: "Yellow" inside the session storage object:
sessionStorage.setItem("pcColor", "Yellow");
// Store laptopColor: "White" inside the session storage object:
sessionStorage.setItem("laptopColor", "White");
// Clear all items from the session storage:
sessionStorage.clear();
// Confirm whether the session storage still contains any item:
console.log(sessionStorage);
// The invocation above will return:
{length: 0}
Example 2: How to clear all items from the local storage object
Invoke localStorage
’s clear()
method.
// Store carColor: "Pink" inside the browser's local storage object:
localStorage.setItem("carColor", "Pink");
// Store pcColor: "Yellow" inside the local storage object:
localStorage.setItem("pcColor", "Yellow");
// Store laptopColor: "White" inside the local storage object:
localStorage.setItem("laptopColor", "White");
// Clear all items from the local storage:
localStorage.clear();
// Confirm whether the local storage still contains any item:
console.log(localStorage);
// The invocation above will return:
{length: 0}
Now that we know what web storage is and how to access it, we can practice using it in a JavaScript project.
Time to Practice with Web Storage 🤸♂️🏋️♀️
Consider the following To-Do List app:
The Problem
The issue with the To-Do List app is this:
- Tasks disappear whenever users refresh the webpage.
Your Exercise
Use the appropriate Web Storage APIs to accomplish the following tasks:
- Prevent the Session pane’s To-Do items from disappearing whenever users reload the browser.
- Prevent the Local section’s To-Do items from disappearing whenever users reload or close their browser tab (or window).
- Auto-display the Session section's previously added tasks on page reload.
- Auto-display the Local section's previously added tasks on page reload (or browser reopen).
Bonus Exercise
Use your browser’s console to:
- Check the number of items in your browser’s session storage object.
- Display the name of your local storage’s zeroth index item.
- Delete all the items in your browser’s session storage.
Note: You will benefit much more from this tutorial if you attempt the exercise yourself.
If you get stuck, don’t be discouraged. Instead, review the lesson and give it another try.
Once you’ve given it your best shot (you’ll only cheat yourself if you don’t!), we can discuss how I approached the exercise below.
How Did You Go About Solving the Web Storage Exercise?
Below are feasible ways to get the exercise done.
How to prevent the Session Storage pane’s To-Do items from disappearing on page reload
Whenever users click the “Add task” button,
- Get existing session storage’s content, if any. Otherwise, return an empty array.
- Merge the existing to-do items with the user’s new input.
- Add the new to-do list to the browser’s session storage object.
Here’s the code:
sessionAddTaskBtn.addEventListener('click', () => {
// Get existing session storage's content, if any. Otherwise, return an empty array:
const currentTodoArray =
JSON.parse(sessionStorage.getItem('codesweetlyStore')) || [];
// Merge currentTodoArray with the user's new input:
const newTodoArray = [
...currentTodoArray,
{ checked: false, text: sessionInputEle.value },
];
// Add newTodoArray to the session storage object:
sessionStorage.setItem('codesweetlyStore', JSON.stringify(newTodoArray));
const todoLiElements = createTodoLiElements(newTodoArray);
sessionTodosContainer.replaceChildren(...todoLiElements);
sessionInputEle.value = '';
});
Note: The three dots (...
) preceding the currentTodoArray
variable represent the spread operator. We used it in the newTodoArray
object to copy currentTodoArray
’s items into newTodoArray
.
How to prevent the Local Storage pane’s To-Do items from disappearing on page reload or reopen
- Get existing local storage’s content, if any. Otherwise, return an empty array.
- Merge the existing to-do items with the user’s new input.
- Add the new to-do list to the browser’s local storage object.
Here’s the code:
localAddTaskBtn.addEventListener('click', () => {
// Get existing local storage's content, if any. Otherwise, return an empty array:
const currentTodoArray =
JSON.parse(localStorage.getItem('codesweetlyStore')) || [];
// Merge currentTodoArray with the user's new input:
const newTodoArray = [
...currentTodoArray,
{ checked: false, text: localInputEle.value },
];
// Add newTodoArray to the local storage object:
sessionStorage.setItem('codesweetlyStore', JSON.stringify(newTodoArray));
const todoLiElements = createTodoLiElements(newTodoArray);
localTodosContainer.replaceChildren(...todoLiElements);
localInputEle.value = '';
});
Note: The localTodosContainer.replaceChildren(...todoLiElements)
statement tells the browser to replace localTodosContainer
’s current children elements with the list of <li>
s in the todoLiElements
array.
How to auto-display the Session section’s previously added tasks on page reload
Whenever users reload the page,
- Get existing session storage’s content, if any. Otherwise, return an empty array.
- Use the retrieved content to create
<li>
elements. - Populate the tasks display space with the
<li>
elements.
Here’s the code:
window.addEventListener('load', () => {
// Get existing session storage's content, if any. Otherwise, return an empty array:
const sessionTodoArray =
JSON.parse(sessionStorage.getItem('codesweetlyStore')) || [];
// Use the retrieved sessionTodoArray to create <li> elements:
const todoLiElements = createTodoLiElements(sessionTodoArray);
// Populate the tasks display space with the todoLiElements:
sessionTodosContainer.replaceChildren(...todoLiElements);
});
How to auto-display the Local section’s previously added tasks on page reload or reopen
Whenever users reload or reopen the page,
- Get existing local storage’s content, if any. Otherwise, return an empty array.
- Use the retrieved content to create
<li>
elements. - Populate the tasks display space with the
<li>
elements.
Here’s the code:
window.addEventListener('load', () => {
// Get existing local storage's content, if any. Otherwise, return an empty array:
const localTodoArray =
JSON.parse(localStorage.getItem('codesweetlyStore')) || [];
// Use the retrieved localTodoArray to create <li> elements:
const todoLiElements = createTodoLiElements(localTodoArray);
// Populate the tasks display space with the todoLiElements:
localTodosContainer.replaceChildren(...todoLiElements);
});
How to check the total items in the browser’s session storage
Use session storage’s length
property like so:
console.log(sessionStorage.length);
How to display the local storage’s zeroth index item’s name
Use the local storage’s key()
method as follows:
console.log(localStorage.key(0));
How to empty the browser’s session storage
Use the session storage’s clear()
method as follows:
sessionStorage.clear();
How to Continue Practicing with Web Storage 🧗♀️🚀
The to-do app still has a lot of potential. For instance, you can:
- Convert it to a React TypeScript application.
- Make it keyboard accessible.
- Allow users to delete or edit individual tasks.
- Allow users to star (mark as important) specific tasks.
- Let users specify due dates.
So, feel free to continue developing what we’ve built in this tutorial so you can better understand the web storage objects.
For instance, here’s my attempt at making the two panes functional:
Before we wrap up our discussion, you should know some differences between web storage and cookies. So, let’s talk about that below.
Web Storage vs. Cookies: What is the Difference?
Web storage and cookies are two main ways to store data locally within a user’s browser. But they work differently. Below are the main distinctions between them.
Storage limit
Cookies: Have 4 kilobytes maximum storage limit.
Web storage: Can store a lot more than 4 kilobytes of data. For instance, Safari 8 can store up to 5 MB, while Firefox 34 permits 10 MB.
Data transfer to the server
Cookies: Transfer data to the server whenever browsers send HTTP requests to the web server.
Web storage: Never transfers data to the server.
Note: It is a waste of users’ bandwidth to send data to the server if such information is needed only by the client (browser), not the server.
Weak integrity and confidentiality
Cookies: Suffer from weak integrity and weak confidentiality issues.
Web storage: Do not suffer from weak integrity and confidentiality issues because it stores data per origin.
Property
Cookies: Cookies are a property of the Document
object.
Web storage: Web storage is a property of the Window
object.
Expiration
Cookie: You can specify a cookie’s expiration date.
Web storage: Browsers determine web storage’s expiration date.
Retrieving individual data
Cookies: There’s no way to retrieve individual data. You always have to recall all the data to read any single one.
Web storage: You can choose the specific data you wish to retrieve.
The syntax for storing data
Cookies:
document.cookie = "key=value";
Web storage:
webStorageObject.setItem(key, value);
The syntax for reading data
Cookies:
document.cookie;
Web storage:
webStorageObject.getItem(key);
The syntax for removing data
Cookies:
document.cookie = "key=; expires=Thu, 01 May 1930 00:00:00 UTC";
The snippet above deletes the cookie by assigning an empty value to the key
property and setting a past expiration date.
Web storage:
webStorageObject.removeItem(key);
Wrapping up
In this article, we discussed how to use web storage and its built-in interfaces. We also used a to-do list project to practice using the local and session storage objects to store data locally and securely within users’ browsers.
Thanks for reading!
And here’s a useful React TypeScript resource:
I wrote a book about Creating NPM Packages!
It is a beginner-friendly book that takes you from zero to creating, testing, and publishing NPM packages like a pro.