Custom Data (data-*) Attributes

by kirupa   |   7 August 2012

In the past, if you ever wanted to mark or tag your elements for any sort of programmatic access later, you didn't have too many good choices. The most common thing you did was add or remove class values from an element:

<img class="ufo friendly healthy" src="spaceship.png">
<img class="ufo enemy destroyed" src="spaceship.png">

That was fine if what you were doing resulted in your element visually changing. There are many times when you just want to store some data on an element - data that you wouldn't want to surface to the user. Overloading the more CSS-oriented class attribute seemed a bit distasteful. Also distasteful was abusing the rel tag, declaring custom namespaces, and doing other things to make up for the lack of a standardized way to embed data into your page.

Fortunately, something sweeter was on the horizon. Starting with HTML5, you have the ability to specify custom data attributes (aka data dash or data-* attributes) whose sole job is to allow you to tag elements with data that you can programmatically access later.

In this short article, let's look at how to define them, how to use them in JavaScript, and glean some nuggets of wisdom concerning their usage.

Say Hello to Custom Data Attributes

Let's say that I have a list of images:

<img src="foo.png"/>
<img src="bar.png"/>
<img src="zorb.png"/>
<img src="blarg.png"/>

What I want to do is store the name of the photographer as part of each image. The way I am going to do this is by using a custom data attribute called photographer:

<img src="foo.png" data-photographer="Bart"/>
<img src="bar.png" data-photographer="Lisa"/>
<img src="zorb.png" data-photographer="Ralph"/>
<img src="blarg.png" data-photographer="Milhouse"/>

Notice how the custom data attribute is defined. Whatever attribute name you are interested in using, simply prefix data- in front of it. You can have as many custom data attributes as you want. In case you were wondering, simply adding a custom data attribute has no bearing on the appearance or layout of an application.

Working with Custom Data Attributes in JS

With custom data attributes, the two most common things you will do is retrieve the value stored by such an attribute or set the value stored by such an attribute.

To retrieve the value stored by a data-* attribute, use the trusty getAttribute method on the HTML element the attribute lives on:

<img id="tv" src="foo.png" data-photographer="Krusty the Clown">

var tvImg = document.getElementById("tv");
var name = tvImg.getAttribute('data-photographer');

To set the value, you use getAttribute's mortal enemy, the setAttribute method. When using the setAttribute method, you specify both the attribute name along with the value you want it to store:

tvImg.setAttribute("data-photographer", "Sideshow Bob");

The helpful thing to note is that your data-* attributes are nothing more than just plain, boring attributes. Everything you could do in JavaScript before with attributes, you can still do now. These attributes are just named a little bit differently. That's all.

The dataset Property

You have another way of programmatically accessing your custom data attributes, and that is via the dataset property. This property is so new that most browser don't implement it today, so I'll defer talking about it now. Everything this property provides you can do using getAttribute and setAttribute anway.

When to use Data-* Attributes

Now that you've seen all of this, a worthy next question to ask is when you should use these data-* attributes in your HTML. There is some amount of mixed opinions on this.

A concise summary of custom data attributes is provided by the WHATWG spec:

Custom data attributes are intended to store custom data private to the page or application, for which there are no more appropriate attributes or elements.

In more friendly terms, here is how I would summarize when you should or shouldn't use custom data attributes:

If you have a question about this or any other topic, the easiest thing is to drop by our forums where a bunch of the friendliest people you'll ever run into will be happy to help you out!


Get cool tips, tricks, selfies, and more...personally hand-delivered to your inbox!

( View past issues for an idea of what you've been missing out on all this time! )



No spam. No fluff. Just awesome content sent straight to your inbox!

Awesome and high-performance web hosting!
new books - yay!!!