jQuery .prop() Method

What You’ll Learn

The .prop() method gets or sets DOM properties on matched elements. This tutorial covers all four API overloads (getter, name/value setter, plain object, callback setter), the critical difference between properties and attributes, comparisons with .attr(), .val(), and .removeProp(), and five official jQuery demos.

Introduction

DOM elements expose properties in JavaScript — live values that reflect current state: whether a checkbox is checked, an input is disabled, or a select option is selected. When you need to read or change that runtime state, jQuery provides .prop().

Introduced in jQuery 1.6, .prop() explicitly separates properties from attributes. Before 1.6, .attr() sometimes returned property values for certain names, causing inconsistent behavior across browsers. Now .attr() handles HTML attributes and .prop() handles DOM properties — each with a clear role.

Use .prop() for checked, disabled, selected, and selectedIndex on form elements. For typed input text, prefer .val() over .prop('value'). For markup values like href and src, use .attr() instead.

Understanding the .prop() Method

Given a jQuery object representing one or more DOM elements, .prop() either reads a property from the first element (getter) or writes properties to every matched element (setter). Getters return any JavaScript value or undefined if the property is not set. Setters return the original jQuery object for chaining.

Properties reflect live DOM state. For a checkbox, prop('checked') returns a boolean that updates when the user clicks. The checked attribute (read via attr('checked')) corresponds to defaultChecked — the initial HTML state — and does not change with user interaction.

📝 Syntax

jQuery .prop() accepts four argument forms:

1. Getter — read one property (since 1.6)

.prop( propertyName )

• propertyName — the name of the property to get.
• Returns Anything or undefined for the first matched element only.

2. Setter — name and value (since 1.6)

.prop( propertyName, value )

• propertyName — the property to set on every matched element.
• value — any value: boolean, number, string, or object.

3. Plain object — set multiple properties (since 1.6)

.prop( properties )

• properties — a plain object of property-value pairs applied to each matched element.

4. Callback setter — computed value per element (since 1.6)

.prop( propertyName, function( index, oldPropertyValue ) {
  // return value to set
} )

• index — zero-based position of the element in the matched set.
• oldPropertyValue — the element’s current property value.
• this — the current DOM element. Return a value to set; return nothing to leave unchanged.

Return value

• Getter — Anything or undefined (first element only).
• Setter — the original jQuery object (for chaining).

Properties vs. attributes

Use .prop() for live DOM state. Use .attr() for HTML attributes in markup:

// Properties — live DOM state on form controls
if ( $("input").prop("checked") ) { /* user checked it */ }
if ( $("option").prop("selected") ) { /* currently selected */ }
$("input").prop("disabled", true);
var idx = $("select").prop("selectedIndex");
// Attributes — initial HTML values (strings)
$("a").attr("href", "/about");

Boolean properties: checked

The checked attribute does not correspond to the checked property. Always test live state with .prop():

// Cross-browser: is the checkbox currently checked?
if ( $("input").prop("checked") ) { /* yes */ }
if ( $("input").is(":checked") ) { /* yes */ }
// Wrong for live state — reflects initial HTML only
// $("input").attr("checked")

Official jQuery API example

$( "input" ).prop( "disabled", false );
$( "input" ).prop( "checked", true );
$( "input" ).val( "someValue" );

Examples Gallery

Examples 1–5 follow the official jQuery API documentation. Use DevTools or the Try-it links to run each snippet in the browser.

$( "input" ).on( "change", function() {
  var $input = $( this );
  $( "p" ).html(
    ".attr('checked'): " + $input.attr( "checked" ) + " <br>" +
    ".prop('checked'): " + $input.prop( "checked" ) + " <br>" +
    ".is(':checked'): " + $input.is( ":checked" )
  );
} ).trigger( "change" );

Unchecked: .attr('checked') → undefined, .prop('checked') → false
Checked:   .attr('checked') → "checked", .prop('checked') → true
.prop() tracks live state — .attr() reflects initial HTML

$( "input[type='checkbox']" ).prop({
  disabled: true
});

All checkboxes become disabled and unclickable
.prop({ disabled: true }) sets the live disabled property

$( "input[type='checkbox']" ).prop( "checked", function( i, val ) {
  return !val;
});

Each click inverts every checkbox
Checked → unchecked, unchecked → checked

$( "#agree" ).prop( "checked", true );
$( "#name" ).prop( "disabled", false ).val( "someValue" );

checked=true, disabled=false, val=someValue
Use .prop() for boolean state — .val() for the text content

var idx = $( "#colors" ).prop( "selectedIndex" );
var text = $( "#colors option:selected" ).text();

selectedIndex=2 (Blue)
Properties like selectedIndex have no attribute — use .prop()

🚀 Common Use Cases

• Form validation gates — if (!$("#agree").prop("checked")) { /* block submit */ }.
• Disable submit buttons — $("button[type=submit]").prop("disabled", true) during Ajax requests.
• Toggle all checkboxes — $(".item").prop("checked", function(i, val){ return !val; }).
• Bulk disable form fields — $("fieldset :input").prop({ disabled: true }).
• Read select position — var idx = $("select").prop("selectedIndex") for index-based logic.
• Enable fields on consent — $("#name").prop("disabled", false).val("") when user agrees.

📝 Notes

• Available since jQuery 1.6 — all four overloads arrived together.
• Getter returns value for the first element only; setters apply to all matches.
• Use .prop() for checked, selected, disabled, and selectedIndex — not .attr().
• Use .val() for getting and setting typed input text — not necessarily .prop('value').
• Do not use .removeProp() on native DOM properties — set them explicitly instead.
• Attempting to change the type property on an input already in the document throws in Internet Explorer 6, 7, and 8.
• In IE prior to version 9, setting a property to a non-primitive value (object, function) can cause memory leaks — use .data() for complex values.

💡 Best Practices