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.
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.
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"> <script> var tvImg = document.getElementById("tv"); var name = tvImg.getAttribute('data-photographer'); </script>
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");
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.
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:
In more friendly terms, here is how I would summarize when you should or shouldn't use custom data attributes:
Got a question or just want to chat? Comment below or drop by our forums (they are actually the same thing!) where a bunch of the friendliest people you'll ever run into will be happy to help you out!
Hit Subscribe to get cool tips, tricks, selfies, and more personally hand-delivered to your inbox.