Summary

DOM Storage is the name given to the set of storage-related features first introduced in the Web Applications 1.0 specification, and now split off into its own W3C Web Storage specification. DOM Storage is designed to provide a larger, securer, and easier-to-use alternative to storing information in cookies. It was first introduced with Firefox 2 and Safari 4.

Description

The DOM Storage mechanism is a means through which string key/value pairs can be securely stored and later retrieved for use. The goal of this addition is to provide a comprehensive means through which interactive applications can be built (including advanced abilities, such as being able to work "offline" for extended periods of time).

Currently, Mozilla-based browsers, Internet Explorer 8, Safari 4+ and Chrome provide a working implementation of the DOM Storage specification. Internet Explorer previous to version 8 does have a similar feature called "userData behavior" that allows you to persist data across multiple browser sessions.

DOM Storage is useful because no good browser-only methods exist for persisting reasonable amounts of data for any period of time. Browser cookies have limited capacity and provide no support for organizing persisted data, and other methods (such as Flash Local Storage) require an external plugin.

One of the first public applications to make use of the new DOM Storage functionality (in addition to Internet Explorer's userData Behavior) was halfnote (a note-taking application) written by Aaron Boodman. In his application, Aaron simultaneously saved notes back to a server (when Internet connectivity was available) and a local data store. This allowed the user to safely write backed-up notes even with sporadic Internet connectivity.

While the concept, and implementation, presented in halfnote was comparatively simple, its creation shows the possibility for a new breed of web applications that are usable both online and offline.

Reference

The following are global objects that exist as properties of every window object. This means that they can be accessed as sessionStorage or window.sessionStorage. (This is important because you can then use IFrames to store, or access, additional data, beyond what is immediately included in your page.)

interface Storage {
  readonly attribute unsigned long length;
  [IndexGetter] DOMString key(in unsigned long index);
  [NameGetter] DOMString getItem(in DOMString key);
  [NameSetter] void setItem(in DOMString key, in DOMString data);
  [NameDeleter] void removeItem(in DOMString key);
  void clear();
};

// Save data to a the current session's store
sessionStorage.setItem("username", "John");

// Access some stored data
alert( "username = " + sessionStorage.getItem("username"));

// Get the text field that we're going to track
 var field = document.getElementById("field");
 
 // See if we have an autosave value
 // (this will only happen if the page is accidentally refreshed)
 if ( sessionStorage.getItem("autosave")) {
     // Restore the contents of the text field
     field.value = sessionStorage.getItem("autosave");
 }
 
 // Check the contents of the text field every second
 setInterval(function(){
     // And save the results into the session storage object
     sessionStorage.setItem("autosave", field.value);
 }, 1000);

// Save data that only scripts on the mozilla.org domain can access
globalStorage['mozilla.org'].setItem("snippet", "<b>Hello</b>, how are you?");

globalStorage['developer.mozilla.org'].setItem("username", "John");

// parseInt must be used since all data is stored as a string
 globalStorage['mozilla.org'].setItem("visits", parseInt(globalStorage['mozilla.org'].getItem("visits") || 0 ) + 1);

Storage location and clearing the data

The DOM storage data is stored in the webappsstore.sqlite file in the profile folder.

• DOM Storage can be cleared via "Tools -> Clear Recent History -> Cookies" when Time range is "Everything" (via nsICookieManager::removeAll)
  • But not when another time range is specified: (bug 527667)
  • Does not show up in Tools -> Options -> Privacy -> Remove individual cookies (bug 506692)
• DOM Storage is not cleared via Tools -> Options -> Advanced -> Network -> Offline data -> Clear Now.
• Doesn't show up in the "Tools -> Options -> Advanced -> Network -> Offline data" list, unless the site also uses the offline cache. If the site does appear in that list, its DOM storage data is removed along with the offline cache when clicking the Remove button.

See also clearing offline resources cache.

More information

• Web Storage (W3C Web Apps Working Group)
• Enable/Disable DOM Storage in Firefox or SeaMonkey

Examples

• JavaScript Web Storage Tutorial: Creating an Address Book Application - hands-on tutorial describing how to use the Web Storage API by creating a simple address book application
• offline web applications at hacks.mozilla.org - showcases an offline app demo and explains how it works.
• Noteboard - Note writing application that stores all data locally.
• jData - A shared localStorage object interface that can be accessed by any website on the internet and works on Firefox 3+, Webkit 3.1.2+ nightlies, and IE8. Think of it as pseudo-globalStorage[""] but write access needs user confirmation.
• HTML 5 localStorage example. Very simple and easy to understand example of localStorage. Saves and retrieves texts and shows a list of saved items. Tested in Firefox 3 or higher.
• HTML5 Session Storage. A very simple example of session storage. Also includes a example on local storage. Tested in Firefox 3.6 or higher.
• Basic DOMStorage Examples - Broken in Firefox 3 and up due to use of globalStorage on one domain level up from the current domain which is not allowed in Firefox 3.
• halfnote - (displaying broken in Firefox 3) Note writing application that uses DOM Storage.

Browser compatibility

All browsers have varying capacity levels for both local- and sessionStorage. Here is a detailed rundown of all the storage capacities for various browsers.

Related

• HTTP cookies (document.cookie)
• Flash Local Storage
• Internet Explorer userData behavior
• nsIDOMStorageEventObsolete
• StorageEvent