The element.dataset API

By  on  

A while back I showed you the awesome classList API, which allows simple addition, removal, and toggling of CSS classes without the need for parsing the className.  Another simple API available in FireFox Aurora Firefox 6, at time of print and Chrome 8 is the element.dataset API.  This tiny API allows developers to get and set data- attribute values on HTML elements.   Let's take a look at how it works!

As you know, you can add information to HTML elements using custom data- attributes.  You can name these data- attributes however you'd like.  There are a few rules for working with the dataset API:

  • element.dataset cannot be referenced directly -- you will receive an error
  • You reference data- property names by camel-casing their attribute names
  • The name cannot start with xml
  • The name cannot contain uppercase letters

Assume the following element is within the page:

<div id="myDiv" data-name="myDiv" data-id="myId" data-my-custom-key="This is the value"></div>

To retrieve the data-id attribute value, you'd code:

// Get the element
var element = document.getElementById("myDiv");

// Get the id
var id =;

To retrieve the data-my-custom-key attribute, you'd code:

// Retrieves "data-my-custom-key"
var customKey = element.dataset.myCustomKey;

Assigning the value to a custom attribute you would look like:

// Sets the value to something else
element.dataset.myCustomKey = "Some other value";

// Element would be:
//		<div id="myDiv" data-name="myDiv" data-id="myId" data-my-custom-key="Some other value"></div>	

If a data- attribute you programmatically set does not exist, it will be created:

// Set new data- attribute
element.dataset.mootoolsFtw = "true";

// Element would be:
//		<div id="myDiv" data-name="myDiv" data-id="myId" data-my-custom-key="Some other value" data-mootools-ftw="true"></div>

It probably goes without saying but you cannot store objects within element.dataset without serializing them first.  I'm not aware of dataset length restrictions but storing large sets of data via dataset will make for a bloated DOM which would be difficult to debug.  I do think this little nugget is useful though!

Recent Features

  • By
    Create Namespaced Classes with MooTools

    MooTools has always gotten a bit of grief for not inherently using and standardizing namespaced-based JavaScript classes like the Dojo Toolkit does.  Many developers create their classes as globals which is generally frowned up.  I mostly disagree with that stance, but each to their own.  In any event...

  • By
    Write Better JavaScript with Promises

    You've probably heard the talk around the water cooler about how promises are the future. All of the cool kids are using them, but you don't see what makes them so special. Can't you just use a callback? What's the big deal? In this article, we'll...

Incredible Demos

  • By
    Creating the Treehouse Frog Animation

    Before we start, I want to say thank you to David for giving me this awesome opportunity to share this experience with you guys and say that I'm really flattered. I think that CSS animations are really great. When I first learned how CSS...

  • By
    Implementing Basic and Fancy Show/Hide in MooTools 1.2

    One of the great parts of MooTools is that the library itself allows for maximum flexibility within its provided classes. You can see evidence of this in the "Class" class' implement method. Using the implement method, you can add your own methods to...


  1. Dutchie

    Yeah, that is useful stuff as long as you’re working with a framework that uses this if available or other ways if not. I think there’s only 1% change you specifically need to target the browser that supports this (atm)…

  2. Thanks for the write-up. I try to avoid this API because it’s certainly not mainstream, but Moo makes it easy to use the data attributes anyways.

    As selectors:


    As data:


    Now, we could have an interesting discussion about whether declarative markup is unobtrusive, but we should have it another day… :)

  3. Savageman

    Opera 11.10+ also supports this, and the Aurora is currently Firefox 6 (if we read the article in 6 months, we won’t be able to guess what was the Aurora when the article was written).

  4. I use the MooTools and element.retrieve quite often. It’s similar to this, but you can store anything, including objects. I’m sure there is a large overhead, but the ability to store a reference to another element is great.

    Such as:

    $$(".someElement").each(function(element) {
        var elementToggler = element.getParent().getParent().getElement(".someToggler");"toggler", elementToggler);
        element.addEvent("mouseenter", function(event) {
        element.addEvent("mouseleave", function(event) {

    You can see that even thought we need a convoluted call to initially get the toggler, once we have the reference we can store it and call it much more easily. You can do that same with things like order numbers, arrays of changed elements, ect.

    You could probably achieve similar functionality by giving the toggler a unique ID and saving it to the element.dataset and calling it back that way, but I think in that particular case, the store/retrieve would have a smaller overhead.

    Actually, looking through the MooTools code, it appears that the store/retrieve function has a very small overhead. It is just storing the data in an object that is referenced to the element. It would actually be really simple to implement on your own.

    var storage = {};
    var get = function(uid){
        return (storage[uid] || (storage[uid] = {}));
    var retrieve = function(element, property, default){
        var storage = get(element.uid), prop = storage[property];
        if (default != null && prop == null) prop = storage[property] = default;
        return prop != null ? prop : null;
    var store = function(element, property, value){
        var storage = get(element.uid);
        storage[property] = value;
        return this;

    This method doesn’t take advantage of the Element implementation, obviously, but it is still simple. The great thing about this is that no string parsing is going on to inject data.

Wrap your code in <pre class="{language}"></pre> tags, link to a GitHub gist, JSFiddle fiddle, or CodePen pen to embed!