In the YUI 3 Gallery: Ryan Grove's Storage Lite Cross-Browser Storage Library

By YUI TeamFebruary 23, 2010

Ryan Grove, Frontend Engineer on Yahoo! SearchRyan Grove (@yaypie on Twitter) is a web developer and pie connoisseur (the former for Yahoo! Search and the latter for fun). He has worked on features like Search Assist, Search Pad, and the recent Search redesign, and is currently helping migrate Yahoo! Search from YUI 2 to YUI 3.

With more and more browsers adding support for the HTML5 Web Storage API, the future is looking good for web applications that need persistent client-side data storage. Unfortunately, maintaining compatibility with older browsers that don't yet support Web Storage can be a challenge, and dropping support for older browsers is rarely an acceptable option.

The Storage Lite YUI 3 Gallery module, which was developed for use on Yahoo! Search, aims to solve this problem by providing a simple, lightweight API wrapper for a variety of persistent client-side storage mechanisms with no external plugin dependencies of any kind (not even Flash). It weighs in at about 2.6KB after minification and before gzip, is similar to the HTML5 localStorage API, and works in IE6+, Firefox 2+, Safari 3.1+, Chrome 4+, and Opera 10.5+.

Apart from being based on YUI 3, Storage Lite differs from the existing YUI 2 Storage Utility in several ways. YUI 2 Storage is a robust and extensible implementation that stays more faithful to the HTML5 localStorage and sessionStorage APIs (for example, it provides a change event and a key() method, which Storage Lite does not). YUI 2 Storage also falls back on Flash or Gears storage for older browsers, which can in some cases provide better persistence and more storage capacity. Storage Lite trades extensibility and plugin-based fallbacks for lighter weight and better performance, and specifically focuses on emulating only localStorage.

Click through to see the example in action.

Take a look at this persistent notepad example to see Storage Lite in action, or read through the following non-interactive code sample for a quick tour of the API.

First, include the script:

<script src="

In your implementation code, listen for the storage-lite:ready event, which is fired when the storage mechanism is ready for use. After the storage mechanism is ready, you can use the API:

YUI().use('gallery-storage-lite', function (Y) {

    // For full compatibility with IE 6-7 and Safari 3.x, listen for the
    // storage-lite:ready event before making storage calls. If you're not
    // targeting those browsers, you can safely ignore this step.
    Y.StorageLite.on('storage-lite:ready', function () {

        // To store an item, pass a key and a value (both strings) to setItem().
        Y.StorageLite.setItem('kittens', 'fluffy and cute');

        // If you set the optional third parameter to true, you can use any
        // serializable object as the value and it will automatically be stored
        // as a JSON string.
        Y.StorageLite.setItem('pies', ['apple', 'pumpkin', 'pecan'], true);

        // To retrieve an item, pass the key to getItem().
        Y.StorageLite.getItem('kittens');    // => 'fluffy and cute'

        // To retrieve and automatically parse a JSON value, set the optional
        // second parameter to true.
        Y.StorageLite.getItem('pies', true); // => ['apple', 'pumpkin', 'pecan']

        // The length() method returns a count of how many items are currently
        // stored.
        Y.StorageLite.length(); // => 2

        // To remove a single item, pass its key to removeItem().

        // To remove all items in storage, call clear().



Data stored using Storage Lite is persisted across pageviews and browser restarts*, and is accessible only from the same domain in which it was stored. Behind the scenes, Storage Lite uses the following storage mechanisms, automatically choosing the best one that's supported:

  • Firefox 3.5+, Chrome 4+, Safari 4+, IE8, Opera 10.5+: HTML5 localStorage — these modern browsers all support the core localStorage functionality defined in the HTML5 draft.
  • Firefox 2.x and 3.0.x: Gecko globalStorage, an early API similar to HTML5’s localStorage.
  • Safari 3.1 and 3.2: HTML5 Database Storage, because Safari 3.1 and 3.2 don’t support HTML5 localStorage.
  • IE6, IE7: userData persistence, a rarely used IE feature for associating string data with an element on a web page and persisting it between pageviews.

For more details, see the Storage Lite GitHub project and the API reference.

* Caveat: IE6 and IE7 persist data across pageviews, but not across browser restarts.