jQuery .data() Method

What You’ll Learn

.data() attaches arbitrary JavaScript values to elements and reads them back — including values seeded from HTML5 data-* attributes. This tutorial covers setters and getters, object merges, data-* conversion, camelCase keys, comparisons with .attr() and jQuery.data(), five examples, and try-it labs.

Introduction

This page covers the collection method .data() (same API as api.jquery.com/data). The low-level static jQuery.data() utility is documented under Utilities.

Plugins and UI widgets often need to remember state on a DOM node — options, counters, objects — without inventing fragile global variables. Since jQuery 1.2.3, .data() is the standard way to do that.

Values live in jQuery’s internal cache (not as expando properties you manage yourself), which helps avoid circular-reference memory leaks. You can store numbers, strings, objects, arrays, and more — anything except undefined.

Since 1.4.3, HTML5 data-* attributes also seed that cache the first time you call .data(). Pair this topic with .removeData(), jQuery.hasData(), and the DOM hub.

Understanding the .data() Method

Think of each element as having a small private dictionary. Writing $(el).data("foo", 52) puts 52 under key foo. Reading $(el).data("foo") returns it. Calling .data() with no arguments returns the whole dictionary for the first matched element.

Setting with an object (since 1.4.3) shallow-merges keys into the existing store — it no longer replaces the entire object like early 1.4 versions did.

📝 Syntax

Common signatures:

.data( key, value )     // set one key (1.2.3+)
.data( obj )            // merge keys from an object (1.4.3+)
.data( key )            // get one key (1.2.3+)
.data()                 // get all data as an object (1.4+)

Parameters

• key (String) — name of the data entry.
• value (Anything except undefined) — value to store.
• obj (Object) — key/value pairs to merge into the cache.

Return value

• Setter — the jQuery collection (chainable).
• Getter with key — the stored value (or undefined).
• Getter with no args — a plain object of all keys for the first element.

Quick set / get (official style)

$( "body" ).data( "foo", 52 );
$( "body" ).data( "bar", { isManual: true } );
$( "body" ).data( { baz: [ 1, 2, 3 ] } );
$( "body" ).data( "foo" ); // 52
$( "body" ).data();        // { foo: 52, bar: {…}, baz: […] }

Examples Gallery

Examples follow the official jQuery API demos and everyday patterns. Use View Output or Try It Yourself to explore each case.

$( "div" ).data( "test", { first: 16, last: "pizza!" } );
$( "span" ).first().text( $( "div" ).data( "test" ).first );
$( "span" ).last().text( $( "div" ).data( "test" ).last );

The values stored were 16 and pizza!
(object stays intact under the "test" key)

$( "button" ).on( "click", function() {
  var value;
  switch ( $( "button" ).index( this ) ) {
    case 0:
      value = $( "div" ).data( "blah" );
      break;
    case 1:
      $( "div" ).data( "blah", "hello" );
      value = "Stored!";
      break;
    case 2:
      $( "div" ).data( "blah", 86 );
      value = "Stored!";
      break;
    case 3:
      $( "div" ).removeData( "blah" );
      value = "Removed!";
      break;
  }
  $( "span" ).text( "" + value );
});

Get → undefined (then hello / 86 after set)
Remove → key gone until you set again

<div id="page"
  data-role="page"
  data-last-value="43"
  data-hidden="true"
  data-options='{"name":"John"}'></div>

$( "#page" ).data( "role" );       // "page"
$( "#page" ).data( "lastValue" );  // 43
$( "#page" ).data( "hidden" );     // true
$( "#page" ).data( "options" ).name; // "John"

role: page (string)
lastValue: 43 (number)
hidden: true (boolean)
options.name: John (parsed object)

$( "#box" )
  .data( "foo", 52 )
  .data( { bar: true, baz: [ 1, 2, 3 ] } );

console.log( $( "#box" ).data() );
// { foo: 52, bar: true, baz: [1, 2, 3] }

foo stays 52
bar and baz are added
Shallow merge — nested objects are not deep-merged

// Markup: <div id="x" data-score="10"></div>
$( "#x" ).data( "score" );          // 10 (number from attribute)
$( "#x" ).data( "score", 99 );      // cache now 99
$( "#x" ).attr( "data-score" );     // still "10" in the DOM

$( "#x" ).attr( "data-score", "50" ); // updates attribute string
// cache may still be 99 until you removeData / re-read carefully

.data write → cache only
.attr write → markup string
Pick one source of truth per key

🚀 Common Use Cases

• Plugin / widget state — options, timers, and flags on the host element.
• Counters and IDs — remember which row or tab is active.
• Config from markup — read data-* into typed values on init.
• Caching computed results — avoid re-querying expensive setup.
• Cleanup with removeData — reset before re-init or destroy.
• Guards with hasData — check whether a cache already exists.

📝 Notes

• Setters since 1.2.3; object setter 1.4.3; no-arg getter 1.4.
• Do not use .data() on <object> (unless Flash), <embed>, or <applet>.
• XML documents: attaching data is not reliably cross-platform (legacy IE note in the docs).
• undefined is not a valid stored value.
• Updating .data() does not update DOM attributes.
• jQuery 3 camelCases dashed keys like the HTML dataset API.
• Getters that take a key operate on the first element in the collection.
• Related: .removeData(), jQuery.hasData(), jQuery.data().

💡 Best Practices