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 predefined special property of browser's window object.

There are 2 storage properties:

for “permanent” storage.
per session.
// example of storing data

// set value
window.localStorage.setItem("xx", "abc");

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

console.log( yy );
// prints "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.)

Turn on Browser Cookies

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 , 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", 123);
console.log( typeof window.localStorage.getItem ("x"));

[see How to Use Browser Console]

Getter and Setter Methods

localStorage has the following methods and properties:

return the key's value.
localStorage.setItem(key, value)
set the key to value.
remove the item.
remove all data.
return the name (string) of the ith item. (Object's property are not ordered. Use this in a “for loop” to access all items.)
number of items.

sessionStorage has the same methods and properties.

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


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

// don't do this
window.localStorage["xx"] = "abc";
const yy = window.localStorage["xx"];

Using the normal syntax of accessing property with Dot Notation or Bracket Notation (example: localStorage.o={"x":1}) creates a semantic inconsistency, because the localStorage is a special property, not a normal JavaScript property. Here's a example:

// example of inconsistency if browser supports storing objects
localStorage.o = {x:1}; // Store a object
localStorage.o.x = 2; // try to set the property of the stored object
localStorage.o.x // returns 1. x is unchanged
// this example is from David Flanagan's JavaScript Definitive Guide
// Note: as of 2014-03-01, browsers only support storing string.

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

What is the difference between localStorage and 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.

JavaScript in Depth

DOM Scripting


DOM Methods

Basic Examples

HTML Input

Web Scripting Examples

Web Scripting Misc