5 Obscure Facts About HTML5 LocalStorage

LocalStorage is a handy API included in the "HTML5" wave that gives web developers an easy to use 5MB store on an users local machine. Using the LocalStorage API really couldn't be easier. It's a simple key/value dictionary with a simple API to match:

    //Save a value to localStorage
    localStorage.setItem('key', 'value to save');
    //OR
    localStorage.key = 'string value to save';

    //Get the value back out of localStorage
    localStorage.getItem('key');
    //OR
    localStorage.key;

    //Clear all localStorage values
    localStorage.clear();

Joining LocalStorage in the HTML5 spec (which, technically, is now the separate Web Storage spec) is also SessionStorage. It provides an identical API, but a different "retention policy." As the name implies, values in SessionStorage should only survive a single browser session (not server session). More this in a moment.

The Storage APIs are so simple, it's easy to rush past them and overlook some important details about their behavior. Here are five things you may not know (or may have forgotten) about this simple API:

1. LocalStorge values on Secure (SSL) pages are isolated

Per the draft spec, browsers isolate LocalStorage values based on scheme + hostname + unique port (also known as an HTML5 Origin). Hostname is expected, since we don't want malicious websites to have access to other websites' LocalStorage data. But scheme (i.e. http and https)?

The result of this separation means that a value saved to LocalStorage on http://htmlui.com cannot be accessed by pages served from https://htmlui.com (and vice versa). There is some good reason for this (I suppose), especially in the case of isolating values created during a secure session from unsecured sessions. But since LocalStorage should never be a place for storing sensitive data, I'm a bit surprised by this separation.

It's the reality, though, so be careful if your site serves both HTTP and HTTPS pages. (NOTE: Firefox provides a proprietary GlobalStorage that does not have this HTTP/HTTPS isolation.)

2. SessionStorage values survive some browser restarts

SessionStorage, unlike LocalStorage, is not designed for long-term persistence of values in the user's browser. Instead, values in SessionStorage are destroyed when a browser session ends, which is usually when the browser window is closed.

There is an exception, though.

When a browser provides a "Restore Session" feature, usually designed to help users quickly recover from a browser/computer crash, values in SessionStorage will be restored, too. So while it's a new "session" on the server, from the browser's perspective, it's a continuation of a single session across a browser restart.

This makes SessionStorage an ideal storage technique for things like temporary "backup" of user form values, saving input to SessionStorage as it's entered and restoring on page load (if it exists) to further help the user recover from a browser crash or accidental page refresh (though browsers do some of this on their own, especially when recovering from a crash).

3. LocalStorage values created in "incognito" mode are isolated

When you fire-up a browser in private/incognito/safe mode (sometimes more crudely- and accurately- referred to as "porn mode"), it will create a new, temporary database for LocalStorage values. That means anything saved to LocalStorage will be destroyed when the private browsing session is closed, making LocalStorage behave more like SessionStorage.

Additionally, since a browser's "Session Restore" feature does not re-open private mode sessions, anything created in SessionStorage will also be lost after the browser window is closed. Really, in short, any data put in Local or SessionStorage during a private browsing session will be lost as soon as the browser window is closed (intentionally or not).

4. LocalStorage quotas cannot be made bigger than 5MB

LocalStorage is not supposed to be the primary form of in-browser storage with HTML5 (IndexDB will eventually come along to provide that), but some apps may want more than the default 5MB LocalStorage provides. Is there a way to expand LocalStorage quotas? No and no.

Technically, the LocalStorage origin restriction does not block sub-domains of the same host (using the same scheme and port) from accessing the same LocalStorage object. As a result, some browsers have exposed a workaround that grants "a1.website.com" and "a2.website.com" their own 5MB LocalStorage quotas. And since both sites are on the same origin, they can access each others values. (SECURITY SIDE NOTE: This also means that sites on shared domains, like apphost.com, all share a single HTML5 Storage object. Proceed with caution!)

So while a technical workaround exists, it is specifically frowned upon in the HTML5 Web Storage spec. Browser authors are asked to prevent multiple sub-domains of a single site from being given a bigger LocalStorage pool. That makes this workaround a "user at your own risk" solution that is likely to break in the future (if it still works today).

Fortunately, the spec further calls on browser authors to prompt users when LocalStorage quotas are reached (allowing users to increase the storage quota), but so far only Opera has implemented this portion of the spec. So for now, 5MB is your realistic limit.

5. LocalStorage can be polyfilled in to older browsers (including IE)

Ah, legacy browsers. The downers at every HTML5 party. Fortunately, LocalStorage is incredibly well supported in Class A browsers. It's natively available in IE8+ (!), Firefox 3.5+, and Chrome 4+. There are few HTML5 specs as broadly and consistently supported as Web Storage.

For older versions of IE, polyfill support is available thanks to an IE-only feature called "userData". Introduced in IE5, userData is an IE behavior that opens-up 1MB of local storage. By wrapping the userData API, modern HTML5 applications can address polyfilled LocalStorage all the way back to IE6 (or IE5, technically).

A few libraries exist that do this for you. Amplify is one such library from appendTo (though it introduces a new API instead of doing pure polyfill), and Remy Sharp has a simple implementation that wraps standard HTTP cookies (severely limiting the API's usefulness, but providing some functionality for older browsers).

So enjoy the simple LocalStorage APIs, but be aware of the inner workings that could create some confusing debugging.

Todd Anglin

About the Author
Todd Anglin is an active speaker and author on HTML5 and web development technologies, speaking at conferences around the globe. He has a background in professional graphic design as well as professional software development. He melds his passions for design and development to currate htmlUI. During the day, Todd serves as Chief Evangelist for Telerik, an agile international software company that builds tools for software developers and development teams, including Kendo UI for HTML5 developers.

Related Posts