HTML Element .dataset

var value = element.dataset.keyName;

element.dataset.keyName = "value";

// Delete a data attribute.
delete element.dataset.keyName;

<div id="user" data-name="user1" data-age="37" data-is-active="true">User Info</div>
<ul id="member-list">
	<li data-member-id="1" data-org="org_a">user1</li>
	<li data-member-id="2" data-org="org_b">user2</li>
	<li data-member-id="3" data-org="org_c">user3</li>
	<li data-member-id="4" data-org="org_d">user4</li>
</ul>
<button id="toggle-btn" data-state="off">Toggle</button>

This produces the following output:

var user = document.getElementById("user");
console.log(user.dataset.name); // Outputs "user1"
console.log(user.dataset.age); // Outputs "37" (a string, not a number)
console.log(user.dataset.isActive); // Hyphen to camelCase. Outputs "true"

user.dataset.role = "boss"; // Adds the data-role attribute.
delete user.dataset.age; // Removes the data-age attribute.

// Pattern 2: Convert to the correct type before use
console.log(user.dataset.isActive === true); // false (string "true" is not boolean true)
console.log(user.dataset.isActive === "true"); // Outputs true

// Pattern 3: Filter list items using data attributes
var items = document.querySelectorAll("#member-list li");
items.forEach(function(item) {
	if (item.dataset.org === "org_a" || item.dataset.org === "org_b") {
		item.style.fontWeight = "bold"; // Bold the matching members.
	}
});

// Pattern 4: Manage toggle state with a data attribute
var toggleBtn = document.getElementById("toggle-btn");
toggleBtn.addEventListener("click", function() {
	if (toggleBtn.dataset.state === "off") {
		toggleBtn.dataset.state = "on";
		toggleBtn.textContent = "ON";
	} else {
		toggleBtn.dataset.state = "off";
		toggleBtn.textContent = "Toggle";
	}
	console.log("Current state: " + toggleBtn.dataset.state);
});

View sample page

Mistake 1: dataset values are always strings

Values retrieved via element.dataset are always strings. Comparing them directly with numbers can produce unexpected results due to type coercion, so convert the value first with Number() or parseInt().

var el = document.getElementById("user");
// NG: dataset.age is the string "37", not the number 37
if (el.dataset.age > 30) {
	console.log("older than 30"); // may not work as expected due to string coercion
}

The following example shows how this works in practice:

var el = document.getElementById("user");
// OK: Convert to a number first
if (Number(el.dataset.age) > 30) {
	console.log("older than 30");
}

Mistake 2: Not knowing how hyphenated names convert to camelCase

Hyphenated data-* attribute names are converted to camelCase when accessed via dataset. Using the original hyphenated key returns undefined, so data-user-id is accessed as dataset.userId.

// NG: The hyphenated key does not work with dataset
var id = el.dataset["user-id"]; // undefined

The corrected version looks like this:

// OK: data-user-id is accessed as dataset.userId
var id = el.dataset.userId; // works correctly

element.dataset is a property that provides access to the custom data attributes (data-* attributes) set on an HTML element. The key name is the attribute name with the data- prefix removed. Hyphenated names are converted to camelCase — for example, data-user-id is accessed as dataset.userId.

Values retrieved via element.dataset are always strings. If a number is needed, the value must be converted using Number() or parseInt(). Boolean-like values such as "true" and "false" are also returned as strings, so a strict comparison like === true will never match.

Data attributes are an officially sanctioned way to embed custom data in HTML. You can also access them with element.getAttribute(), but element.dataset provides more intuitive object-property-style access and makes reading and writing more concise.