# Web Storage

# Using localStorage

The localStorage object provides persistent (but not permanent - see limits below) key-value storage of strings. Any changes are immediately visible in all other windows/frames from the same origin. The stored values persistent indefinitely unless the user clears saved data or configures an expiration limit. localStorage uses a map-like interface for getting and setting values.

localStorage.setItem('name', "John Smith");
console.log(localStorage.getItem('name')); // "John Smith"

localStorage.removeItem('name');
console.log(localStorage.getItem('name')); // null

If you want to store simple structured data, you can use JSON (opens new window) to serialize it to and from strings for storage.

var players = [{name: "Tyler", score: 22}, {name: "Ryan", score: 41}];
localStorage.setItem('players', JSON.stringify(players));

console.log(JSON.parse(localStorage.getItem('players')));
// [ Object { name: "Tyler", score: 22 }, Object { name: "Ryan", score: 41 } ]

# localStorage limits in browsers

Mobile browsers:

Browser	Google Chrome	Android Browser	Firefox	iOS Safari
Version	40	4.3	34	6-8
Space available	10MB	2MB	10MB	5MB

Desktop browsers:

Browser	Google Chrome	Opera	Firefox	Safari	Internet Explorer
Version	40	27	34	6-8	9-11
Space available	10MB	10MB	10MB	5MB	10MB

# Simpler way of handling Storage

localStorage, sessionStorage are JavaScript Objects and you can treat them as such.
Instead of using Storage Methods like .getItem(), .setItem(), etc… here's a simpler alternative:

// Set
localStorage.greet = "Hi!"; // Same as: window.localStorage.setItem("greet", "Hi!");

// Get
localStorage.greet;         // Same as: window.localStorage.getItem("greet");

// Remove item
delete localStorage.greet;  // Same as: window.localStorage.removeItem("greet");

// Clear storage
localStorage.clear();

Example:

// Store values (Strings, Numbers)
localStorage.hello = "Hello";
localStorage.year  = 2017;    

// Store complex data (Objects, Arrays)
var user = {name:"John", surname:"Doe", books:["A","B"]};
localStorage.user = JSON.stringify( user );

// Important: Numbers are stored as String
console.log( typeof localStorage.year ); // String

// Retrieve values
var someYear = localStorage.year; // "2017"

// Retrieve complex data
var userData = JSON.parse( localStorage.user );
var userName = userData.name; // "John"

// Remove specific data
delete localStorage.year; 

// Clear (delete) all stored data
localStorage.clear();

# Storage events

Whenever a value in set in localStorage, a storage event will be dispatched on all other windows from the same origin. This can be used to synchronize state between different pages without reloading or communicating with a server. For example, we can reflect the value of an input element as paragraph text in another window:

var input = document.createElement('input');
document.body.appendChild(input);

input.value = localStorage.getItem('user-value');

input.oninput = function(event) {
  localStorage.setItem('user-value', input.value);
};

var output = document.createElement('p');
document.body.appendChild(output);

output.textContent = localStorage.getItem('user-value');

window.addEventListener('storage', function(event) {
  if (event.key === 'user-value') {
    output.textContent = event.newValue;
  }
});

# Notes

Event is not fired or catchable under Chrome, Edge and Safari if domain was modified through script.

// page url: http://sub.a.com/1.html
document.domain = 'a.com';

var input = document.createElement('input');
document.body.appendChild(input);

input.value = localStorage.getItem('user-value');

input.oninput = function(event) {
  localStorage.setItem('user-value', input.value);
};

// page url: http://sub.a.com/2.html
document.domain = 'a.com';

var output = document.createElement('p');
document.body.appendChild(output);

// Listener will never called under Chrome(53), Edge and Safari(10.0).
window.addEventListener('storage', function(event) {
  if (event.key === 'user-value') {
    output.textContent = event.newValue;
  }
});

# sessionStorage

The sessionStorage object implements the same Storage interface as localStorage. However, instead of being shared with all pages from the same origin, sessionStorage data is stored separately for every window/tab. Stored data persists between pages in that window/tab for as long as it's open, but is visible nowhere else.

var audio = document.querySelector('audio');

// Maintain the volume if the user clicks a link then navigates back here.
audio.volume = Number(sessionStorage.getItem('volume') || 1.0);
audio.onvolumechange = function(event) {
  sessionStorage.setItem('volume', audio.volume);
};

Save data to sessionStorage

sessionStorage.setItem('key', 'value');

Get saved data from sessionStorage

var data = sessionStorage.getItem('key');

Remove saved data from sessionStorage

sessionStorage.removeItem('key')

# Clearing storage

To clear the storage, simply run

localStorage.clear();

# Error conditions

Most browsers, when configured to block cookies, will also block localStorage. Attempts to use it will result in an exception. Do not forget to manage these cases (opens new window).

var video = document.querySelector('video')
try {
    video.volume = localStorage.getItem('volume')
} catch (error) {
    alert('If you\'d like your volume saved, turn on cookies')
}
video.play()

If error were not handled, program would stop functioning properly.

# Remove Storage Item

To remove a specific item from the browser Storage (the opposite of setItem) use removeItem

localStorage.removeItem("greet");

Example:

localStorage.setItem("greet", "hi");
localStorage.removeItem("greet");

console.log( localStorage.getItem("greet") ); // null

(Same applies for sessionStorage)

# localStorage length

localStorage.length property returns an integer number indicating the number of elements in the localStorage

Example:

Set Items

localStorage.setItem('StackOverflow', 'Documentation');
localStorage.setItem('font', 'Helvetica');
localStorage.setItem('image', 'sprite.svg');

Get length

localStorage.length; // 3

# Syntax

localStorage.setItem(name, value);

localStorage.getItem(name);

localStorage.name = value;

localStorage.name;

localStorage.clear()

localStorage.removeItem(name);

# Parameters

Parameter	Description
name	The key/name of the item
value	The value of the item

# Remarks

The Web Storage API is specified in the WHATWG HTML Living Standard (opens new window).

← Cookies Data attributes →