Using data attributes

O HTML5 foi criado pensando na extensibilidade dos dados que precisam ser associados a um determinado elemento mas não necessariamente tem um significado definido.  Atributos data-* nos permite armazenar informações extras em elementos HTML padrões e semânticos, sem a necessidades de hacks como classList, atributos fora do padrão, propriedades extras no DOM ou o método depreciado setUserData.

HTML Syntax

A sintaxe é simples. Qualquer atributo de qualquer elemento no qual o nome do atributo inicia com data- é um atributo data. Digamos que você possui um article e quer armazenar informações extras que não possuem nenhuma representação visual. Use atributos data para isso:

<article
  id="electriccars"
  data-columns="3"
  data-index-number="12314"
  data-parent="cars">
...
</article>

JavaScript Access

Ler os valores destes atributos via JavaScript é muito simples também. Você pode lê-los usando getAttribute() com o nome html completo, mas a forma padrão provê uma alternativa mais simples: um DOMStringMap pode ser lido através da propriedade dataset.

Para obter o atributo data através do objeto dataset, acesse a propriedade utilizando a parte do nome do atributo após o prefixo data- (note que o hífen é convertido para camelCase).

var article = document.getElementById('electriccars');
 
article.dataset.columns // "3"
article.dataset.indexNumber // "12314"
article.dataset.parent // "cars"

Cada propriedade é uma String e pode ser lida e escrita. No exemplo acima a atribuição article.dataset.columns = 5 iria alterar esse atributo para "5".

CSS Access

Note that, as data attributes are plain HTML attributes, you can even access them from CSS. For example to show the parent data on the article you can use generated content in CSS with the attr function:

article::before {
  content: attr(data-parent);
}

You can also use the attribute selectors in CSS to change styles according to the data:

article[data-columns='3'] {
  width: 400px;
}
article[data-columns='4'] {
  width: 600px;
}

You can see all this working together in this JSBin example. 

Data attributes can also be stored to contain information that is constantly changing, like scores in a game. Using the CSS selectors and JavaScript access here this allows you to build some nifty effects without having to write your own display routines. See this screencast for an example using generated content and CSS transitions (JSBin example).

Since data values are strings, all values must have quotes or else the styling won't have any effect.

Issues

Do not store content that should be visible and accessible in data attributes, because assistive technology may not access them. In addition, search crawlers may not index data attributes' values. 

The main issues to consider are Internet Explorer support and performance. Internet Explorer 11+ provides support for the standard, but all earlier versions do not support dataset. To support IE 10 and under you need to access data attributes with getAttribute()  instead. Also, the performance of reading data-attributes compared to storing this data in a JS data warehouse is bad. Using dataset is even slower than reading the data out with getAttribute().

That said, though, for custom element-associated metadata, they are a great solution.

See also

• This article is adapted from Using data attributes in JavaScript and CSS on hacks.mozilla.org.
• How to use HTML5 data attributes (Sitepoint)