JavaScript: Web Storage Tutorial

By Xah Lee. Date: . Last updated: .

Web Storage is a mechanism for JavaScript to store data in client's browser. It's like cookies, but more clean and powerful. [see Get Cookie, Set Cookie]

Web Storage is very simple. It's just a two properties of browser's window object.

window.localStorage
for “permanent” storage.
window.sessionStorage
per session.
/* example of storing data */

window.localStorage.setItem("xx", "abc");

const yy = window.localStorage.getItem("xx");

console.log(yy === "abc");

The data is saved in browser. When user visits the site later, the data will still be available. (if user didn't clear browser data.)

Require Browser Cookies On

If browser's cookies is turned off, web storage won't work. If you try to set storage when cookies is off, you get this error in Firefox:

SecurityError: The operation is insecure.

String Data Only

As of 2023-01-14, only string can be saved. (that is, the value of any property of localStorage is always string data type) Any other value types, such as number or object, will be converted to string. Same for sessionStorage.

[see Value Types]

You can try by typing the following in your browser's console:

window.localStorage.setItem("x", [3, 4]);
console.log(
  typeof window.localStorage.getItem("x") === "string",
);

window.localStorage.setItem("y", 3);
console.log(
  typeof window.localStorage.getItem("x") === "string",
);

[see How to Use Browser Console]

Getter and Setter Methods

localStorage and sessionStorage have the following methods and properties:

.setItem(key, value)
set the key to value.
window.localStorage.setItem("xx", "abc");
console.log(
  window.localStorage.getItem("xx") === "abc",
);
.getItem(key)
return the key's value.
.removeItem(key)
remove the item.
.clear()
remove all data.
.key(i)
return the name (string) of the ith item. (Object's property are not ordered. Use this in a “for loop” to access all items.)
.length
number of items.

It's better if you use these methods to access/set properties.

Example:

/* bad */
window.localStorage["yy"] = "123";
console.log(
  window.localStorage["yy"] === "123",
);

View Storage Data from Browser's Developer Tool

Browsers have dev tools to let you view storage data.

Google Chrome browser dev tool local storage screenshot 2014-03-01
Google Chrome browser dev tool, showing the local storage data.

Web Storage, Same Origin Policy

Data stored in localStorage and sessionStorage can only be accessed from a page that has the “same origin” as the current page, by the “same origin policy”.

A “origin” is the combination of {protocol used, host name, port number}.

For example, none of the following URLs have the same origin.

This also applies to embedded iframes in a page. (that is, if the embedded iframe is loaded from a URL that's not the same origin, then, the iframe's JavaScript cannot access the storage data.)

localStorage vs sessionStorage

localStorage is “permanent”. The data remains unless the user deletes it thru the browser's “clear browser data” feature.

sessionStorage is per session only. The data will be gone when user closes the tab, window, or quit browser.

BUY
ΣJS
JavaScript in Depth

DOM Scripting

Overview

DOM Methods

Basic Examples

HTML Input

Web Scripting Examples

Web Scripting Misc