HTMLOrForeignElement.dataset

The dataset read-only property of the HTMLOrForeignElement 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.

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.

An HTML data-* attribute and its corresponding DOM dataset.property modify their shared name according to where they are read or written:

In HTML
The attribute name begins with data-. It can contain only letters, numbers, dashes (-), periods (.), colons (:), and underscores (_). Any ASCII capital letters (A to Z) are ignored and converted to lowercase.
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.

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

Name conversion

dash-style to camelCase conversion

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

  1. Remove the prefix data- (including the dash);
  2. For any dash (U+002D) followed by an ASCII lowercase letter a to z, remove the dash and uppercase the letter;
  3. Other characters (including other dashes) are left unchanged.
camelCase to dash-style conversion

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

  1. Restriction: Before transformation, a dash must not be immediately followed by an ASCII lowercase letter a to z;
  2. Add the data- prefix;
  3. Add a dash before any ASCII uppercase letter A to Z, then lowercase the letter;
  4. Other characters are left unchanged.

For example, a data-abc-def attribute corresponds to dataset.abcDef.

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

Syntax

const dataAttrMap = element.dataset

Value

A DOMStringMap.

Examples

<div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>John Doe</div>
const el = document.querySelector('#user');

// el.id === 'user'
// el.dataset.id === '1234567890'
// el.dataset.user === 'johndoe'
// el.dataset.dateOfBirth === ''

// set a data attribute
el.dataset.dateOfBirth = '1960-10-03';
// Result: el.dataset.dateOfBirth === '1960-10-03'

delete el.dataset.dateOfBirth;
// Result: el.dataset.dateOfBirth === undefined

if ('someDataAttr' in el.dataset === false) {
  el.dataset.someDataAttr = 'mydata';
  // Result: 'someDataAttr' in el.dataset === true
}

Specifications

Specification Status Comment
HTML Living Standard
The definition of 'HTMLElement.dataset' in that specification.
Living Standard No change from latest snapshot, HTML 5.1
HTML 5.1
The definition of 'HTMLElement.dataset' in that specification.
Recommendation Snapshot of HTML Living Standard, no change from HTML5
HTML5
The definition of 'HTMLElement.dataset' in that specification.
Recommendation Snapshot of HTML Living Standard, initial definition.

Browser compatibility

Update compatibility data on GitHub
DesktopMobile
ChromeEdgeFirefoxInternet ExplorerOperaSafariAndroid webviewChrome for AndroidFirefox for AndroidOpera for AndroidSafari on iOSSamsung Internet
datasetChrome Full support 8Edge Full support 12Firefox Full support 6IE Full support 11Opera Full support 11Safari Full support 5.1WebView Android Full support 4.4Chrome Android Full support 18Firefox Android Full support 6Opera Android Full support 11Safari iOS Full support 5.1Samsung Internet Android Full support 1.0

Legend

Full support  
Full support

See also