data-* Attributes and dataset

A data attribute is a custom attribute on an HTML element whose name starts with data-. It lets you attach your own information to an element without inventing a new attribute or using a non-standard one. The dataset object gives you typed access to those attributes.

// The DOM only exists in a browser, so check before using it.
if (typeof document !== "undefined") {
  const button = document.createElement("button");
  button.dataset.userId = "42";
  button.dataset.role = "admin";

  console.log(button.dataset.userId);                 // "42"
  console.log(button.getAttribute("data-user-id"));  // "42"
  console.log(button.dataset.role);                   // "admin"
  console.log(Object.keys(button.dataset));           // ["userId", "role"]
} else {
  console.log("No DOM in this runtime - open a browser console to try it.");
}

The naming rule is the detail that trips people up. In the attribute itself you write a hyphenated name such as data-user-id, and in the dataset object the same attribute appears as the camelCase key userId. Setting dataset.userId writes the attribute data-user-id, and reading it back gives you the same string. Values are always strings, because that is what attributes hold.

Data attributes are a good fit for values that describe an element for your own code to read later, such as an id, a role or a state. They are a poor fit for values that drive styling, because you cannot select on an attribute value and keep the styling in one place the way you can with classes. And they are not a place to put application state, because they are visible in the markup and in the inspector, and they survive page loads in ways that surprise people.

There is a fixed conversion rule. A data attribute name has the prefix data- followed by the key in hyphenated lowercase. The dataset property converts that into camelCase, dropping the prefix and capitalising the letter after each hyphen.

// The DOM only exists in a browser, so check before using it.
if (typeof document !== "undefined") {
  const el = document.createElement("div");
  el.dataset.userId = "42";
  el.dataset.maxRetryCount = "3";

  console.log(el.getAttribute("data-user-id"));          // "42"
  console.log(el.getAttribute("data-max-retry-count"));  // "3"

  // The dataset object is a live view of the attributes.
  el.setAttribute("data-role", "admin");
  console.log(el.dataset.role);   // "admin"

  // Removing an attribute removes the dataset key too.
  el.removeAttribute("data-role");
  console.log("role" in el.dataset);   // false
} else {
  console.log("No DOM in this runtime - open a browser console to try it.");
}

Two consequences of the conversion rule. A hyphen always means the next letter is capitalised, so a key written with a capital already, such as maxRetryCount, produces data-max-retry-count rather than something with a double capital. And you cannot express a key containing an uppercase letter followed by another letter in a way that round-trips exactly, because the conversion is one way and lossy at the boundary.

The live view property is genuinely useful and often missed. The dataset object is not a snapshot. Writing an attribute with setAttribute makes the matching dataset key appear immediately, and removing an attribute makes the key disappear. That means you can mix the two styles freely within the same element.

One more thing to know. The dataset object only exposes attributes that begin with data-, and only on the element it belongs to. It does not reach into attributes that are not data attributes, and it does not give you a view of the whole attribute set. For that you use the attributes collection or the getAttributeNames method.

Select the elements with an attribute selector, then read the dataset value inside the loop. The attribute selector uses the hyphenated form, because that is how the attribute appears in the markup.

// The DOM only exists in a browser, so check before using it.
if (typeof document !== "undefined") {
  const items = [...document.querySelectorAll("[data-id]")];

  for (const item of items) {
    console.log(item.dataset.id, item.textContent.trim());
  }

  // Collect them into an object instead of reading one at a time.
  const index = Object.fromEntries(
    items.map((item) => [item.dataset.id, item.textContent.trim()])
  );
  console.log(index);
} else {
  console.log("No DOM in this runtime - open a browser console to try it.");
}

The attribute selector is the important part. Writing the selector as data-id rather than as dataId matches the attribute in the markup, and it is how you select elements that carry a particular data attribute without adding a class purely for selection purposes.

Two practical notes. The spread into an array is worth doing, because querySelectorAll returns a static node list which already behaves like an array for most purposes, but converting it means you can use the array methods directly. And the dataset values are always strings, so if the attribute holds a number you have to convert it yourself before doing arithmetic with it.

When the data is needed often, building an index object once and looking values up in it is much cheaper than walking the DOM on every interaction. That is the same idea as caching, and it shows up in real applications where a list is rendered from data and the data attributes are how the click handler finds out which row was clicked.