Attributes, properties and the data cache

attr versus prop versus data, why the data cache surprises people, and how to read form values without guessing.

attr and prop are not interchangeable

// Attributes are the HTML as written. Properties are the live DOM state.
const checkbox = document.getElementById('terms');

console.log(checkbox.getAttribute('checked'));   // "" once set in the markup, never changes
console.log(checkbox.checked);                   // true/false, follows the user

$('#terms').attr('checked');    // reads the attribute — reflects the initial markup
$('#terms').prop('checked');    // reads the property — reflects reality

// The rule of thumb: prop for state booleans, attr for HTML that is genuinely markup.
$('#terms').prop('checked', true);              // check it
$('#terms').prop('disabled', false);            // enable it
$('#link').attr('href', '/next');               // change the destination
$('#img').attr('alt', 'Product photo');         // change an attribute
$('#field').attr('data-state', 'dirty');        // custom data attributes go through attr

The data cache

// .data() reads data-* attributes ONCE, then caches. After that it is
// a private store: writing with .data() does NOT touch the attribute.
const $el = $('#cart');

// markup: <div id="cart" data-count="3" data-options='{"gift":true}'></div>
$el.data('count');          // 3      (number — jQuery converts the string)
$el.data('options');        // { gift: true }  (parsed JSON)
$el.attr('data-count');     // "3"    (the raw string)

$el.data('count', 4);       // writes to the CACHE only
$el.attr('data-count');     // still "3"  — the attribute is unchanged
$el.data('count');          // 4

// To write through to the attribute you must set it explicitly.
$el.attr('data-count', 4);

// Later markup changes are invisible to the cache.
$el.attr('data-count', 99);
$el.data('count');          // still 4 — the cache wins

// .removeData() clears one key; it does not touch the attribute.
$el.removeData('count');

// The trap in practice: two components disagreeing about the same value.
function cartCount() {
  return $('#cart').data('count');     // reads the cache
}
function serverSays(n) {
  $('#cart').attr('data-count', n);    // writes the attribute
}
serverSays(7);
console.log(cartCount());              // 3 or 4 — NOT 7

// Pick one source of truth per value and stay with it:
//   server-rendered values   -> .attr('data-x') on read and write
//   client-only state        -> .data('x') and never look at the attribute
//   anything real            -> a plain variable or a store, with the DOM as a render target

Class and form value helpers

$('#panel').addClass('is-open');
$('#panel').removeClass('is-open');
$('#panel').toggleClass('is-open', shouldOpen);           // second arg forces a state
$('#panel').hasClass('is-open');                          // boolean
$('#panel').toggleClass('is-open is-dirty');              // multiple at once

// Reading form state correctly
$('#terms').is(':checked');                               // boolean property
$('#plan').val();                                         // selected option's value
$('#plan option:selected').text();                        // its label
$('input[name="tags"]:checked')                           // a checkbox group
  .map((_, el) => el.value)
  .get();                                                 // ['red', 'blue']

// prop on a collection applies to every element and returns the collection
$('.js-select-all').prop('checked', true);

// Attributes for things assistive technology reads
$('#accordion-trigger').attr('aria-expanded', 'true');
$('#dialog').attr('aria-hidden', 'false');
$('#live-region').text('Saved.');

• .map() on a jQuery collection returns a jQuery-wrapped array; .get() unwraps it into a plain JavaScript array.
• .toggleClass(name, state) with a boolean is the safe form. Without it, calling toggle twice from two sources produces a class that flickers.
• Use .prop() for aria-*? No — ARIA attributes are attributes, so .attr() is correct there. State booleans on the element itself use prop.
• The class attribute is the intersection of markup and behaviour. Choose one owner — usually a framework or a component class — and let everything else toggle through it.

FAQ

Related

DOM manipulation, insertion and cloning Form handling, serialization and validation

Last refreshed 2026-09-18.