Introduction

The Web Storage API includes two related mechanisms for persisting client-side data in a secure manner using the Document Object Model (DOM),  sessionStorage and localStorage. These objects were introduced in Windows Internet Explorer 8.

 Note: For versions of Windows Internet Explorer prior to version 8, persistent data storage is implemented by the userData behavior.

What is DOM Storage?

Web Storage is often compared to HTTP cookies.  Like cookies, Web developers can store per-session or domain-specific data as name/value pairs on the client using Web Storage.  However, unlike cookies, Web Storage makes it easier to control how information stored by one window is visible to another.

For example, a user might open two browser windows to buy airline tickets for two different flights. However, if the airline's Web application uses cookies to store its session state, information could "leak" from one transaction into the other, potentially causing the user to buy two tickets for the same flight without noticing.  As applications become more capable of offline behaviours, such as storing values locally for later return to the server, the potential for this sort of information "leak" becomes more prevalent.

Web Storage also offers significantly more disk space than cookies.  In Internet Explorer, cookies can store only 4 kilobytes (KB) of data.  This byte total can be one name/value pair of 4 KB, or it can be up to 20 name/value pairs that have a total size of 4 KB.  By comparison, Web Storage provides roughly 10 megabytes (MB) for each storage area.

Functionally, client storage areas are quite different from cookies.  Web Storage doesn't transmit values to the server with every request as cookies do, nor does the data in a local storage area ever expire.  And unlike cookies, it is easy to access individual pieces of data using a standard interface that has growing support among browser vendors.

window.sessionStorage

Session storage is designed for scenarios where the user is carrying out a single transaction. The sessionStorage attribute of the window object maintains key/value pairs for all pages loaded during the lifetime of a single tab (for the duration of the top-level browsing context).  For example, a page might have a check box that the user selects to indicate that he wants insurance.

<label>     
	<input type="checkbox" onchange="sessionStorage.insurance = checked">     
	I want insurance on this trip. 
</label> 

A later page could then check, from script, whether the user had selected the check box.

if (sessionStorage.insurance) { ... }  

The Storage object supports expando properties ('insurance' in the preceding example).  If the property name does not exist, a key/value pair is automatically created to hold it.  Note that key/value pairs are always stored as strings.  Different data types such as numbers, Boolean values, and structured data must be converted to strings before persisting to a storage area.

After a value has been saved to sessionStorage, it can be retrieved by script running in another page in the same context.  When another document is loaded, sessionStorage is initialised from memory for same-origin URLs.  (See Security and Privacy section for more information.)

 Note:  Although it is allowed by the HTML5 (Working Draft), Internet Explorer 8 does not resume  sessionStorage after browser crash recovery.

window.localStorage

The local storage mechanism spans multiple windows and persists beyond the current session. The localStorage attribute provides persistent storage areas for domains. It allows Web applications to store nearly 10 MB of user data, such as entire documents or a user's mailbox, on the client for performance reasons.

For example, a Web site can display a count of how many times the user has visited a page with the following script.

<p>   
  You have viewed this page   
  <span id="count">an untold number of</span>   
  time(s). 
</p> 
<script>   
  var storage = window.localStorage;   
  if (!storage.pageLoadCount) storage.pageLoadCount = 0;   
  storage.pageLoadCount = parseInt(storage.pageLoadCount, 10) + 1;   
  document.getElementById('count').innerHTML = storage.pageLoadCount; 
</script>  

 Note:  Before incrementing pageLoadCount it must first be converted to a number with the parseInt Method (JScript 5.6).

Each domain and subdomain has its own separate local storage area. Domains can access the storage areas of subdomains, and subdomains can access the storage areas of parent domains. For example, localStorage['example.com'] is accessible to example.com and any of its subdomains. The subdomain  localStorage['www.example.com'] is accessible to example.com, but not to other subdomains, such as mail.example.com.

The Storage Object

The following properties and methods are supported by both session and local storage objects.

Web Storage Events