The dataset
read-only property of the HTMLOrForeignElement
interface provides read/write access to all the custom data attributes (data-*
) set on the element. This access is available both in HTML and within the DOM. It is a map of DOMString
s (DOMStringMap
) with one entry for each custom data attribute. Note that 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. Note also that an HTML data-
attribute and its corresponding DOM dataset.
property do not share the same name, but they are always similar:
- In HTML, the name of a custom data attribute begins with
data-
. It must contain only letters, numbers, and the following characters: dash (-
), dot (.
), colon (:
), underscore (_
)—but NOT any ASCII capital letters (A
toZ
). - In JavaScript, the name of a custom data attribute is the name of the same HTML attribute, but in camelCase and with no dashes, dots, etc.
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
tocamelCase
conversion-
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 lettera
toz
, the dash is removed, and the letter is transformed into its uppercase counterpart; - Other characters (including other dashes) are left unchanged.
- The prefix
camelCase
todash-style
conversion-
The opposite transformation, which maps a key to an attribute name, uses the following rules:
- Restriction: Before the transformation, a dash must not be immediately followed by an ASCII lowercase letter
a
toz;
- The prefix
data-
is added; - Any ASCII uppercase letter
A
toZ
is transformed into a dash, followed by its lowercase counterpart; - Other characters are left unchanged.
- Restriction: Before the transformation, a dash must not be immediately followed by an ASCII lowercase letter
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
.
Accessing values
- Attributes can be set and read by using the camelCase name (the key) like an object property of the dataset, as in
element.dataset.keyname
- Attributes can also be set and read using the bracket syntax, as in
element.dataset[keyname]
- The
in
operator can be used to check whether a given attribute exists.
Setting values
- When an attribute is set, its value is always converted into a string.
-
For example:
null
is converted into the string"null"
.
-
- To remove an attribute, you can use the
delete
operator.
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 the data attribute el.dataset.dateOfBirth = '1960-10-03'; // Result: el.dataset.dateOfBirth === 1960-10-03 delete el.dataset.dateOfBirth; // Result: el.dataset.dateOfBirth === undefined // '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
Desktop | Mobile | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
dataset | Chrome Full support 8 | Edge Full support 12 | Firefox Full support 6 | IE Full support 11 | Opera Full support 11 | Safari Full support 5.1 | WebView Android Full support 4.4 | Chrome Android Full support 18 | Firefox Android Full support 6 | Opera Android Full support 11 | Safari iOS Full support 5.1 | Samsung Internet Android Full support 1.0 |
Legend
- Full support
- Full support
api.HTMLOrForeignElement.dataset
after BCD is updated.See also
- The HTML
data-*
class of global attributes. - Using data attributes
Element.getAttribute()
andElement.setAttribute()