HTMLElement.dataset

The HTMLElement.dataset read-only property allows access, both in reading and writing mode, to all the custom data attributes (data-*) set on the element. It is a map of DOMString, one entry for each custom data attribute.

The name of a custom data attribute begins with data-. It must contain only letters, numbers and the following characters: dash (-), dot (.), colon (:), underscore (_). Moreover, it should not contain ASCII capital letters (A to Z).

A custom data attribute name is transformed to a key for the DOMStringMap entry with the following rules

  • the prefix data- is removed (including the dash);
  • for any dash (U+002D) followed by an ASCII lowercase letter a to z, the dash is removed and the letter is transformed into its uppercase counterpart;
  • other characters (including other dashes) are left unchanged.

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

  • Restriction: A dash must not be immediately followed by an ASCII lowercase letter a to z (before the transformation);
  • a prefix data- is added;
  • any ASCII uppercase letter A to Z is transformed into a dash followed by its lowercase counterpart;
  • other characters are left unchanged.

The restriction in the rules above ensures that the two transformations are the inverse one of the other.

For example, the attribute named data-abc-def corresponds to the key abcDef.

Syntax

string = element.dataset.camelCasedName;
element.dataset.camelCasedName = string;

Examples

<div id="user" data-id="1234567890" data-user="johndoe" data-date-of-birth>John Doe
</div>

var el = document.querySelector('#user');

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

el.dataset.dateOfBirth = '1960-10-03'; // set the DOB.

// 'someDataAttr' in el.dataset === false

el.dataset.someDataAttr = 'mydata';
// 'someDataAttr' in el.dataset === true

Specifications

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

Browser compatibility

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
Basic support 8 6.0 (6.0) 11 11.10 6
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support (Yes) 6.0 (6) (Yes) (Yes) (Yes)

See also

  • The HTML data-* class of global attributes.

Document Tags and Contributors

Last updated by: teoli,