HTML5 Custom Data Attributes (data-*)

Have you ever found yourself using element class names or rel attributes to store arbitrary snippets of metadata for the sole purpose of making your JavaScript simpler? If you have, then I have some exciting news for you! If you haven't and you're thinking, Wow, that's a great idea! I implore you to rid your mind of that thought immediately and continue reading.

Thanks to HTML5, we now have the ability to embed custom data attributes on all HTML elements. These new custom data attributes consist of two parts:

Attribute Name

The data attribute name must be at least one character long and must be prefixed with 'data-'. It should not contain any uppercase letters.

Attribute Value

The attribute value can be any string.

Using this syntax, we can add application data to our markup as shown below:

We can now use this stored data in our site’s JavaScript to create a richer, more engaging user experience. Imagine that when a user clicks on a vegetable a new layer opens up in the browser displaying the additional seed spacing and sowing instructions. Thanks to the data- attributes we’ve added to our <li> elements, we can now display this information instantly without having to worry about making any Ajax calls and without having to make any server-side database queries.

Prefixing the custom attributes with data- ensures that they will be completely ignored by the user agent. As far as the browser and indeed the website’s end user are concerned, this data does not exist.

The spec says (emphasis ours):

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.

These attributes are not intended for use by software that is independent of the site that uses the attributes.

Every HTML element may have any number of custom data attributes specified, with any value.

How can I use data attributes?

As custom data attributes are valid HTML5, they can be used in any browser that supports HTML5 doctypes. Thankfully, this is pretty much all of them. In addition to aiding backwards compatibility, this also ensures that custom data attributes will remain a scalable, cross-platform solution well into the future.

Now that we have a broad understanding of what data attributes are, let's take a look at how they can be used:

To store the initial height or opacity of an element which might be required in later JavaScript animation calculations

To store data about the health, ammo, or lives of an element in a JavaScript game

To power accessible JavaScript <video> subtitles as demonstrated by Bruce Lawson

What shouldn’t I use data attributes for?

Although flexible, data attributes aren’t an appropriate solution for all problems.

Data attributes should not be used if there is a existing attribute or element which is more appropriate for storing your data. For example, date/time data should probably be presented semantically in a time element instead rather than stored in custom data attributes.

Custom data attributes are not intended to compete with microformats. It is clearly stated in the spec that the data is not intended to be publicly usable. External software should not interact with it. Marking up contact details or event details using custom data attributes would be wrong, unless of course it is only intended to be used by your own internal scripts.

The presence/absence of a particular data attribute should not be used as a CSS hook for any styling. Doing so would suggest that the data you are storing is of immediate importance to the user and should be marked up in a more semantic and accessible manner.

Using data- attributes with JavaScript

Now that we understand what custom data- attributes are and when we can use them, we should probably take a look at how we can interact with them using JavaScript.

If we wanted to retrieve or update these attributes using existing, native JavaScript, then we can do so using the getAttribute and setAttribute methods as shown below:

This method will work in all modern browsers, but it is not how data- attributes are intended to be used. The second (new and improved) way to achieve the same thing is by accessing an element’s dataset property. This dataset property — part of the new HTML5 JavaScript APIs — will return a DOMStringMap object of all the selected element's data- attributes. When using this approach, rather than using the full attribute name, you can ditch the data- prefix and refer to the custom data directly using the name you have assigned to it. Data attribute names which contain hyphens will be stripped of their hyphens and converted to CamelCase.

If, at some point in your script, a specific data- attribute becomes redundant and is no longer needed, it is also possible to completely remove that attribute from the DOM element by setting it to a value of null.

plant.dataset.leaves = null; // Caterpillars attack!

Unfortunately, the new dataset property has not yet been implemented in any browser, so in the meantime it’s best to use getAttribute and setAttribute as demonstrated earlier.

While developing your application, you may find it useful to be able to select elements based on the presence of — or indeed the specific values of — their custom data- attributes. This can be achieved quickly and easily using querySelectorAll as shown below:

A word of warning

As data attributes become more widely used, the potential for clashes in naming conventions becomes much greater. If you use an unimaginative attribute name such as data-height, then it is likely you will eventually come across a library or plugin that uses the same attribute name. Multiple scripts getting and setting a common data- attribute will probably cause chaos. In order to avoid this, I encourage people to choose a standard string (perhaps the site/plugin name) to prefix all their data- attributes — e.g. data-html5doctor-height or data-my-plugin-height.

Summary

Custom data- attributes are a great way to simplify the storage of application data in your web pages. Although you can’t utilise the new JavaScript APIs just yet, you can enjoy great success using getAttribute and setAttribute safe in the knowledge that they will work in all major browsers.

Homework

If you’re super keen to have a play with the new dataset property but disappointed that it hasn’t been implemented, fear not!, for there is a light at the end of the tunnel. You might be interested in looking at Dr Remy’sexperimental code, which partially enables the dataset functionality in some browsers by editing the Element.prototype.

The code supports the retrieval of data- attributes in the latest versions of Firefox, Safari, Opera, and Chrome, but sadly will not work in any version of IE (since IE does not expose the Element object). This code also partially supports the setting of data attributes, but it will only store the new attribute values within the JavaScript and will not update the DOM element as a full, native implementation of the dataset property would. Although this code is mainly a proof of concept, it may be useful for mobile application or intranet development in closed environments where cross-browser (IE) compatibility is not an issue.

Category

Tags

This article was written by Chris Bewick. Chris Bewick is a front end developer currently working at Yell.com in Reading, England. When he isn't tinkering with html, css and javascript you may well find him snowboarding, BBQing or playing guitar. You can find out more about Chris by subscribing to his 140 character ramblings or by clicking around his blog.

45 Responses on the article “HTML5 Custom Data Attributes (data-*)”

I firmly do not see why it is inappropriate to use custom data attributes for external applications provided that these external applications are not a requirement for viewing the page.

I am the author of a Firefox extension named Local Load. My extension allows developers to save bandwidth by using custom data attributes so that any user with the extension installed will instead load common JavaScript frameworks (e.g. jQuery, Prototype, etc.) from the hard drive rather than download them from the Web. If a user does not have the extension installed it will still load the framework from the Web, so there is nothing wrong there. The extension needs some form of additional markup to let it know that the script can be replaced, what the script is, and what the version is. The most appropriate mechanism of doing this is a custom data attribute. Just trying to guess what the version/script is could potentially break a ton of sites, so I would prefer to keep the script replacement feature an opt-in mechanism.

I don’t understand why this article quotes the part of the spec saying data-* attributes are site-specific, and then gives a warning promoting namespacing. If you follow the spec, you’re creating all of the attribute names, so there’s zero reason for namespacing. That’s exactly why that’s in the spec.

For example (and IIRC the spec mentions this) a widget’s controls (like a tree view) may have data attributes, but the data attributes may have been created using a specific library, such as jQuery or Dojo – so to avoid data attribute collisions the application module may want to namespace it.

I can’t see where Chris referred to the data attribute being site-specific (but it’s late and I may have missed it).

There’s a lot of cases where you won’t want or need to use namespacing, but there are some cases where it makes sense. But since this just builds on existing content attributes rules – you’re free to decide how you use them.

I’m using the data-* with getAttribute and setAttribute since I saw a post about that 2 years ago by Jon Resig, so I can confirm that this way of using it works for all browsers/platforms, starting with IE6.
I just hope that any browser implementing data-* natively won’t break the getAttribute method (it shouldnt but we never know)

From a performance point of view, accessing the DOM via getAttribute() is obviously slower than accessing to a JS variable, event stored in an array, so the use case you give of a JS game using it to store values will probably never happen : developers will use it to transmit info from server to client, but once the DOM has been harvested, it’s best to keep all the values in JS for quicker access

I guess the initial health and ammo data could be stored in a database and using a data-attribute would be a valid mechanism to transfer this information to the game’s javascript. But once this initialisation task is complete there is very little point in continuing to make costly DOM updates with the latest health/ammo stats.

Your article mentions that you shouldn’t use data-* for CSS hooks. What if the data-* attribute was used in the JS but you also wanted to apply styles to it. Wouldn’t it make sense to target the attribute rather than add a secondary class.

Pretty cool feature, although no browsers support it yet. This little bit of code works to add support for the dataset property to any browser that supports __defineGetter__. I wrote it before I realized you linked some code that does pretty much the same thing. My code, on the other hand, has support for actually udpating the attribute values, but it does not support adding new attributes.

The data-* certainly will be useful, but that carrot example isn’t a great example. You would use the data in data-* attributes for, not for display of content. As you say, “It is clearly stated in the spec that the data is not intended to be publicly usable”

You should include the content in actual html text, not in your attributes. That way your data is search engine indexed, accessible to machines in a readable format, etc. If I got the gt and lt right, it’d be something like:

My take is that if you’re creating classes that will never be styled, or storing variables in hidden form fields that never get read from on the server, those are both good use cases for the data- attribute.

However, you should ask yourself, “will I ever want to style this info or create any user feedback based on this data?”

Thanks for the explanation of the data- attributes. Microsoft are planning on incorporating HTML data- attributes into the next version of ASP.NET webforms in their validator controls, and your article helped me out a lot when I was trying to get my head around it all … !

I’ve found a case where I feel using the data-* attributes for CSS hooks is valid. Feedback is, of course, welcome.

I have an HTML table of data that can be sorted, ascending and descending, with AJAX by clicking on the column headers. I opted to use a data-sort-dir=”asc” attribute on the column header to not only tell the AJAX call which direction to sort the request, but also to create an arrow next to the column header indicating which direction the arrow points.

a[data-sort-dir="asc"] {
/* Show the ascending arrow */
}

a[data-sort-dir="desc"] {
/* Show the descending arrow */
}

When a column header is clicked, the data-sort-dir attribute is updated or moved to properly reflect which direction is being sorted.

I also agree that the carrot example was a poor example since you’re storing data to display to the user in another method which was stated to be against the spec. In that case, the hidden element option David R posed in the comments or using the title attribute probably would’ve been better.

@Andres – data-* is only for storing data which is to be used within your own website. As the primary purpose of ARIA roles is to communicate additional page structure to the browser/screenreader this would not be an appropriate time to use them. Stick with role=”main”.

I use the data attributes a lot for jQuery apps. This attribute is for you to store private data for your application. If you are planning to have data understood by the search engines, you could use microdata which is more semantic.

Hi
I’ve found an issue with the data attribute. If we put long number as value of data attribute ( data-longnumber = 111111111111111222222222222222222222233333333333333333333333333333333333333333333333333331111111111111111122222222222222222222222222222222222222222222222222222222211111111111 )
and when fetched using jquery
$(‘div’).data(‘longnumber’)
it returns an exponential value ( 1.1111111111111112e+209)
What will be the issue?
Is there any solution for this?

Is there any guideline for consuming RDFa in XHTML5?
As per my limited understanding, DOCTYPE is ignored within these files, version attribute is deprecated. I’m using <link rel="profile" href="http://www.w3.org/1999/xhtml/vocab"/> within head tag.
The property attribute is used by creative commons license I’m placing at the file’s footer.

Since we’re talking scripting and thus the DOM
setAttribute has been specified as capable since DOM Core 1.0 to set user defined attributes and there are no implementation issues.

Those of us however that script xml documents, including htmlN.. documents, usually use an object reference to elements and store user defined variables there as they are faster to access and address any scripting need:

var a=elobj[‘elementid’].user_defined_attribute;

is faster than

var a=element.getAttribute(user_defined_attribute);

and can address any scripting need that data-* or any other markup language scripting feature pretends to introduce or provide.

Expando properties and “data-*” attributes aren’t quite the same thing.

if someone write :
<div src="image.png"></div>

How can the validators/engines knows that the author didn’t want to write
<img src="image.png">

With “data-*” attributes, it’s possible to know the Author’s intention.

If someone write:
<div data-src="image.png"></div>

He probably meant it.

That’s how Microsoft got wrong and continue to be.
Admitingly, expando properties were a good idea (On the implemenation side, it means LESS validation required) but not as good than requiring “data-” prefix.

Also, imagine than in HTML6, divs can take a “src” attribute to load asynchronous content. (Eg. you are rendering something complex so you want the user to not wait in front of a blank page)
Without the “data-” attribute, you can’t simply change your doctype to “html6”, it makes migration harder.

With the “data-*” attribute you are certain that your html website won’t be broken because the spec did add a new attribute.

isn’t using/storing data values in html markup a bad design?
so if we consider things like single responsibility principle(not like a design pattern that it is,but like a word of wisdom),aren’t we messing up with what HTML is designed to do???

s there any guideline for consuming RDFa in XHTML5?
As per my limited understanding, DOCTYPE is ignored within these files, version attribute is deprecated. I’m using within head tag.
The property attribute is used by creative commons license I’m placing at the file’s footer.