JavaScriptDomBeginner

dataset (data-*)

Reads/writes data-* attributes via a convenient JS object interface.

Review the syntaxStudy the examplesOpen the coding app
el.dataset.key = 'value';
const v = el.dataset.key;
Open Coding Reference

This static page keeps the syntax and examples indexed for search, while the coding app handles interactive exploration and saved references.

What it does

Overview

Reads/writes data-* attributes via a convenient JS object interface.

The HTMLElement.dataset property provides read/write access to custom data attributes (data-*) on elements. It exposes a DOMStringMap, which maps hyphen-separated attribute names to camelCase keys. For example, data-test-id becomes dataset.testId. While convenient, dataset is slightly less performant than getAttribute() for single lookups because it involves parsing all data- attributes into an object. A key edge case involves type conversion: since values are stored as strings, numeric or boolean data must be manually parsed via Number() or comparison. Setting a property to undefined in the dataset will set the attribute value to the string 'undefined', while using the delete operator removes the attribute entirely. Keys cannot begin with 'xml' and must not contain semicolons. For legacy browser support, IE 10 and below do not support dataset, requiring the use of getAttribute() and setAttribute() instead.

Quick reference

Syntax

el.dataset.key = 'value';
const v = el.dataset.key;

See it in practice

Examples

1

Basic Manipulation and Mapping

const el = document.createElement('div');
el.dataset.userRole = 'editor';
el.dataset.lastLogin = '2023-05-01';

console.log(el.dataset.userRole);
console.log(el.getAttribute('data-last-login'));
console.log(el.outerHTML);
Output:
"editor" "2023-05-01" "<div data-user-role=\"editor\" data-last-login=\"2023-05-01\"></div>"

Demonstrates how camelCase properties in JavaScript map to hyphenated attributes in HTML.

2

Parsing Boolean and Numeric Values

const div = document.createElement('div');
div.setAttribute('data-is-active', 'true');
div.setAttribute('data-count', '5');

const isActive = div.dataset.isActive === 'true';
const count = Number(div.dataset.count);

console.log(typeof div.dataset.isActive, isActive);
console.log(typeof div.dataset.count, count);
Output:
"string", true "string", 5

Values in dataset are always strings. They must be explicitly cast to booleans or numbers for logical operations.

3

Removing Attributes via Delete

const span = document.createElement('span');
span.dataset.temporaryId = '12345';

console.log(span.hasAttribute('data-temporary-id'));
delete span.dataset.temporaryId;
console.log(span.hasAttribute('data-temporary-id'));
Output:
true false

Using the delete operator on a dataset property removes the corresponding data-* attribute from the DOM element.

Debug faster

Common Errors

1

LogicError

Cause: Expecting numeric types or booleans from dataset values automatically.

Fix: Explicitly convert the value using Number(), or check the string value for equality.

const age = el.dataset.age; console.log(age + 1); // Returns '251' instead of 26 if age was '25'
2

ReferenceError

Cause: Using hyphenated strings as keys within the dataset object (e.g., el.dataset['user-id']).

Fix: Always use camelCase when accessing the dataset property in JavaScript.

const id = el.dataset['user-id']; // undefined; use el.dataset.userId instead

Runtime support

Compatibility

BrowserAll modern browsers, IE11+ (partial earlier)Modern DOM

Source: MDN Web Docs

Common questions

Frequently Asked Questions

Reads/writes data-* attributes via a convenient JS object interface.

LogicError: Explicitly convert the value using Number(), or check the string value for equality. ReferenceError: Always use camelCase when accessing the dataset property in JavaScript.