jQuery Data

You can use what has been described so far to work with data in HTML tags, but jQuery has a better way. However, it is important to realize that jQuery takes the basic facilities offered by the Dataset API and extends them. In particular, jQuery uses its own method of storing the data in an object and not the dataset property, with two basic functions.

The data function will set and retrieve the data associated with a key. That is:

.data(key,value)

stores the value with the specified key and: 

.data(key)

returns the value associated with the key.

jQuery 3 changed the workings of these functions so that they make use of the full Dataset API. Before this custom attributes were used. What this means is that the data function makes use of any data-* attributes in the HTML tags to supply initial values. However, it is important to notice that the data function does not make use of the dataset property to store new values, it implements a data storage of its own in a new property added to the object. If the value isn't set in the new property it retrieves it from the dataset property but when you store a new value it doesn't change the dataset property. 

For example with the button still defined as:

<button data-mydata-x="myvalue" 
        data-mydata-y="10" 
        data-mydata-z=20">
test1
</button>

you can retrieve the values using:

alert($("button").data("mydataX")); 
alert($("button").data("mydataY"));
alert($("button").data("mydataZ"));

Notice that we have to use the camel-cased key names derived from the attributes used in the tag.

As well as retrieving values you can also set values:

$("button").data("mydataX","30");

In this case you still use the camel-cased key names. The rule is that dashes are used in the tags but not in the JavaScript. However, notice that setting mydataX does not change the dataset property that was created from the tag's attributes. That is:

$("button").data("mydataX","10"); 
alert($("button").prop("dataset").mydataX);

still displays the tag’s original attribute, myvalue, and not 10.

You can also pass an object with key value pairs to set a range of key values. Similarly a call to data with no parameters returns an object with key value pairs. In fact, it returns the dataset property of the DOM element.

For example:

alert($("button").data().mydataX);

gives the same result as: 

alert($("button").data("mydataX"));

Retrieving all of the data values is faster than getting each one at a time. You can also keep a reference to the object and work with it safely unless you use a .data(obj) call to set all of the values in one go.

jQuery also converts the string values stored in the tag attributes to more appropriate data types – numeric values, true and false etc. 

The removeData function is fairly obvious – it removes data that you previously set but notice that it doesn't remove the attributes from the tags. This means that the next time you do a call to data() you will get the original data as set by the tags, i.e. the initial values.

For example, with the button defined earlier, if you do:

$("button").data("mydataX","30").removeData("mydataX"); 
alert($("button").data("mydataX"));

then you will see the original data value and not 30. That is, removeData removes the property that jQuery used to store the value not the property used by the Dataset API.

If you want to remove the data item including from the tag you need to use .removeAttr() as well, but remember to use the attribute name complete with data- and dashes.

For example after:

$("button").data("mydataX","30").removeData("mydataX")
                           .removeAttr("data-mydata-x");

any attempt to access mydataX after this returns undefined. 

You can remove all of the data changes you have made by calling removeData and you can also supply a list of keys to be reset as an array. 

This is almost all there is to say about data and HTML tags, but there are two lower-level functions that work with DOM Elements rather than jQuery object. In most cases it is better to work with a jQuery results object, but for completeness we have jQuery.data() and jQuery.removeData(). These work in the same way as data and removeData, but you have to specify a DOM element as the first parameter.

So, for example:

var ele=$("button")[0]; 
$.data(ele,"mydataX","30");

is the same as:  

$("button").data("mydataX","30");

They are used internally by jQuery.

Data in Objects

There is a little known extension of the Dataset API implemented by jQuery. You can use the same functions that you use to work with data on DOM elements to work with standard JavaScript objects. If you wrap a JavaScript object as a jQuery object than you can use .data() to set key/value pairs.

The data is stored in the original object in a new property that is added called jQuery{randomnumber}. No key name transformations are made and no tags are involved – this is pure JavaScript. This is also the mechanism that jQuery uses to implement data on DOM elements so bypassing the dataset property which holds the values set by the data-* attributes.

For example:

$(myObj).data("mykey","mydata");
console.log( $(myObj).data("mykey"));

will display mydata on the console. 

Notice that removeData doesn't work on objects.

You might be wondering why you would add data to objects in this way - after all you can simply add data as standard properties?

In earlier versions of jQuery it was possible to make use of two custom events associated with any change that occurred to the data. This, however, has been removed from jQuery 3 and no longer works. It is fairly easy to create a new custom event and so restore the missing feature. However, unless there is a very specific reason to do so it is better to use standard JavaScript object properties.