html5 laboratory - using localStorage

Using localStorage

21st September 2010

The experiment

Another one of the new features in HTML5 are localStorage and sessionStorage (which will be discussed elsewhere) which effectively replace cookies (although cookies won't disappear and will still be supported). One major difference between this and cookies is that it separates session data and long term data correctly. Storing data in localStorage bases it around that domain and all windows that are open on it (within your browser). No expiry exists, it's there until you clear it.

In this experiment, I'll mention the interface of the API and show you how to use localStorage to save and retrieve a simple string and an object.

The process

To begin with, lets take a quick look at the (incredibly simple) API that is offered with web storage:

interface Storage {  
   readonly attribute unsigned long length;  
   getter DOMString key(in unsigned long index);  
   getter any getItem(in DOMString key);  
   setter creator void setItem(in DOMString key, in any value);  
   deleter void removeItem(in DOMString key);  
   void clear();  
};

The names are pretty self explanatory, but before we dive into the code, let's take a quick glance at browser compatibility. localStorage is supported in the following:

Firefox 3.5+
Safari 4.0+
Chrome 4.0+
Opera 10.5+
Internet Explorer 8.0+ (I know!)
iPhone 2.0+
Android 2.0+

Hell's teeth, even Internet Explorer 8.0 supports it! Right, onto some code.

Single Value

Let's say we want to let someone type in their name, and then the next time they go to our page, we'll say hello to them. I'll assume you know how to put an input field and a button/link on a page so I'll leave that bit out (if not, there's an example anyway). So the input field that stores the name has an id of name so in order to store it in localStorage we say:

localStorage.setItem('name', document.getElementById('name').value);

That's it, the name is stored.

If we want to retrieve it later:

alert("Hello " + localStorage.getItem('name'));

And if the person is bored with their name and wants to change it, it can be cleared with:

localStorage.removeItem('name');

And it's gone! If they re-enter their name without clearing it, the existing value will just be overwritten.

Of course, there's an example of this which you can see in action and look at the code.

Multiple Values (in an Object)

If we'd like to store more than just a person's name, we can do so with an object. You will, however, require a browser that supports something like JSON (which most modern browsers do) in order to "stringify" and parse the data.

As well as their name, we'd like their location and what they do for a living. Again add in some input fields to retrieve the data (called name, location and job respectively) and the details can be saved in the following way:

var userDetails = {
   name: document.getElementById('name').value,
   location: document.getElementById('location').value,
   job: document.getElementById('job').value
};
localStorage.setItem('userDetails', JSON.stringify(userDetails));

This data can then be retrieved and displayed using the following code:

var userDetails = JSON.parse(localStorage.getItem('userDetails'));
alert("Name: " + userDetails.name + "\rLocation: " + userDetails.location + "\rJob: " + userDetails.job);

I have put together a small example of this in action for you to see.

That's all there is to it really. Naturally you should probably so some error checking around these values, in case nothing has been entered or nothing is stored, but that's common sense and I'm sure you will do that anyway!

The results

localStorage is quite useful and much more developer friendly to use than cookies. Also the fact that once it's set it can be read from all windows on that domain for that user (in that browser) makes it more powerful.