Skip to main content

data-* and HTMLElement.dataset

data-*​

The data-* global attributes form a class of attributes called custom data attributes, that allow proprietary information to be exchanged between the HTML and its DOM representation by scripts.

All such custom data are available via the HTMLElement interface of the element the attribute is set on. The HTMLElement.dataset property gives access to them.

HTMLElement.dataset​

The dataset read-only property of the HTMLElement interface provides read/write access to custom data attributes (data-) on elements. It exposes a map of strings (DOMStringMap) with an entry for each data- attribute.

Example​

HTML
<body>
    <h2 id="title">Dataset-Test</h2>
    <div id="myDiv" data-name="Jim" data-age="41" data-place-of-birth="New York">
</body>
Javascript
const myDiv = document.getElementById("myDiv");
console.log(myDiv.dataset);
Console Output: Object DOMStringMap (dataset)
{
  "name": "Jim",
  "age": "41",
  "placeOfBirth": "New York"
}

The name of the properties is automatically modified in JavaScript. The property name of a custom data attribute is the same as the HTML attribute without the data- prefix, and removes single dashes (-) for when to capitalize the property's "camelCased" name (e.g. data-place-of-birth => placeOfBirth).

note

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

Accessing values​

  • Attributes can be set and read by the camelCase name/key as an object property of the dataset:

    element.dataset.keyname;

  • Attributes can also be set and read using bracket syntax:

    element.dataset["keyname"];

  • The in operator can check if a given attribute exists:

    "keyname" in element.dataset;

Setting values​

  • When the attribute is set, its value is always converted to a string.

    For example:

    element.dataset.example = null;

    is converted into

    data-example="null"

  • To remove an attribute, you can use the delete operator:

    delete element.dataset.keyname;