HTMLElement: dataset property

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since July 2015.

Thedataset read-only propertyof theHTMLElement interface provides read/write access tocustom data attributes(data-*) on elements. It exposes a map of strings(DOMStringMap) with an entry for eachdata-* attribute.

Note:Thedataset property itself can be read, but not directly written.Instead, all writes must be to the individual properties within thedataset, which in turn represent the data attributes.

Value

ADOMStringMap.

An HTMLdata-* attribute and its corresponding DOMdataset.property modify their shared name according to wherethey are read or written:

In HTML: The attribute name begins withdata-. It can contain only letters,numbers, dashes (-), periods (.), colons (:),and underscores (_). AnyASCII capital letters (A toZ) are converted to lowercase.
In JavaScript: The property name of a custom data attribute is the same as the HTML attributewithout thedata- prefix. Single dashes (-) are removed, and the next ASCIIcharacter after a removed dash is capitalized to form the property's camel-cased name.

Details and examples of converting between the HTML and JavaScript forms is described in more detail in the next section.

In addition to the information below, you'll find a how-to guide for using HTML dataattributes in our articleUsing data attributes.

Name conversion

dash-style tocamelCase conversion

A custom data attribute name is transformed to a key for theDOMStringMap entry by the following:

Lowercase all ASCII capital letters (A toZ);
Remove the prefixdata- (including the dash);
For any dash (U+002D) followed by an ASCII lowercase lettera toz, remove the dash and uppercase the letter;
Other characters (including other dashes) are left unchanged.

camelCase todash-style conversion

The opposite transformation, which maps a key to an attribute name, uses thefollowing:

Restriction: Before transformation, a dashmust not beimmediately followed by an ASCII lowercase lettera toz;
Add thedata- prefix;
Add a dash before any ASCII uppercase letterA toZ,then lowercase the letter;
Other characters are left unchanged.

For example, adata-abc-def attribute corresponds todataset.abcDef.

Accessing values

Attributes can be set and read by the camelCase name/key as an object property ofthe dataset:element.dataset.keyname.
Attributes can also be set and read using bracket syntax:element.dataset['keyname'].
Thein operator can check if a given attribute exists:'keyname' in element.dataset. Note that this will walk theprototype chain ofdataset and may be unsafe if you have external code that may pollute the prototype chain. Several alternatives exist, such asObject.hasOwn(element.dataset, 'keyname'), or just checking ifelement.dataset.keyname !== undefined.

Setting values

When the attribute is set, its value is always converted to a string.For example:element.dataset.example = null isconverted intodata-example="null".
To remove an attribute, you can use thedelete operator:delete element.dataset.keyname.

Examples

html

<div data-id="1234567890" data-user="carinaanand" data-date-of-birth>  Carina Anand</div>

const el = document.querySelector("#user");// el.id === 'user'// el.dataset.id === '1234567890'// el.dataset.user === 'carinaanand'// el.dataset.dateOfBirth === ''// set a data attributeel.dataset.dateOfBirth = "1960-10-03";// Result on JS: el.dataset.dateOfBirth === '1960-10-03'// Result on HTML: <div data-id="1234567890" data-user="carinaanand" data-date-of-birth="1960-10-03">Carina Anand</div>delete el.dataset.dateOfBirth;// Result on JS: el.dataset.dateOfBirth === undefined// Result on HTML: <div data-id="1234567890" data-user="carinaanand">Carina Anand</div>if (el.dataset.someDataAttr === undefined) {  el.dataset.someDataAttr = "mydata";  // Result on JS: 'someDataAttr' in el.dataset === true  // Result on HTML: <div data-id="1234567890" data-user="carinaanand" data-some-data-attr="mydata">Carina Anand</div>}