.prop()

Get the value of a property for the first element in the set of matched elements. Set one or more properties for the set of matched elements.

.prop(propertyName)

propertyName StringThe name of the property to get.

The .prop() method gets the property value for only the first element in the matched set. It returns undefined for the value of a property that has not been set, or if the matched set has no elements. To get the value for each element individually, use a looping construct such as jQuery's .each() or .map() method.

Note: Attempting to change the type property (or attribute) of an input element created via HTML or already in an HTML document will result in an error being thrown by Internet Explorer 6, 7, or 8.

Attributes vs. Properties

The difference between attributes and properties can be important in specific situations. Before jQuery 1.6, the .attr() method sometimes took property values into account when retrieving some attributes, which could cause inconsistent behavior. As of jQuery 1.6, the .prop() method provides a way to explicitly retrieve property values, while .attr() retrieves attributes.

For example, selectedIndex, tagName, nodeName, nodeType, ownerDocument, defaultChecked, and defaultSelected should be retrieved and set with the .prop() method. Prior to jQuery 1.6, these properties were retrievable with the .attr() method, but this was not within the scope of attr. These do not have corresponding attributes and are only properties.

Concerning boolean attributes, consider a DOM element defined by the HTML markup <input type="checkbox" checked="checked" />, and assume it is in a JavaScript variable named elem:

elem.checkedtrue (Boolean) Will change with checkbox state
$( elem ).prop( "checked" )true (Boolean) Will change with checkbox state
elem.getAttribute( "checked" )"checked" (String) Initial state of the checkbox; does not change
$( elem ).attr( "checked" ) (1.6+)"checked" (String) Initial state of the checkbox; does not change
$( elem ).attr( "checked" ) (pre-1.6)true (Boolean) Changed with checkbox state

According to the W3C forms specification, the checked attribute is a boolean attribute, which means the corresponding property is true if the attribute is present at all—even if, for example, the attribute has no value or is set to empty string value or even "false". This is true of all boolean attributes.

Nevertheless, the most important concept to remember about the checked attribute is that it does not correspond to the checked property. The attribute actually corresponds to the defaultChecked property and should be used only to set the initial value of the checkbox. The checked attribute value does not change with the state of the checkbox, while the checked property does. Therefore, the cross-browser-compatible way to determine if a checkbox is checked is to use the property:

  • if ( elem.checked )
  • if ( $( elem ).prop( "checked" ) )
  • if ( $( elem ).is( ":checked" ) )

The same is true for other dynamic attributes, such as selected and value.

Display the checked property and attribute of a checkbox as it changes.

JS
<input id="check1" type="checkbox" checked="checked" />
<label for="check1">Check me</label>
<p></p>
CSS
p {
  margin: 20px 0 0;
}
b {
  color: blue;
}
HTML
$("input")
  .change(function () {
    var $input = $(this);
    $("p").html(
      '.attr( "checked" ): <b>' +
        $input.attr("checked") +
        "</b><br>" +
        '.prop( "checked" ): <b>' +
        $input.prop("checked") +
        "</b><br>" +
        '.is( ":checked" ): <b>' +
        $input.is(":checked") +
        "</b>"
    );
  })
  .change();
DEMO

.prop(propertyName, value)🡢 jQuery

propertyName StringThe name of the property to set.
value AnythingA value to set for the property.

.prop(properties)🡢 jQuery

properties PlainObjectAn object of property-value pairs to set.

.prop(propertyName, function(indexInteger, oldPropertyValueAnything))🡢 jQuery

propertyName StringThe name of the property to set.
function(indexInteger, oldPropertyValueAnything) FunctionA function returning the value to set. Receives the index position of the element in the set and the old property value as arguments. Within the function, the keyword this refers to the current element.

The .prop() method is a convenient way to set the value of properties—especially when setting multiple properties, using values returned by a function, or setting values on multiple elements at once. It should be used when setting selectedIndex, tagName, nodeName, nodeType, ownerDocument, defaultChecked, or defaultSelected. Since jQuery 1.6, these properties can no longer be set with the .attr() method. They do not have corresponding attributes and are only properties.

Properties generally affect the dynamic state of a DOM element without changing the serialized HTML attribute. Examples include the value property of input elements, the disabled property of inputs and buttons, or the checked property of a checkbox. The .prop() method should be used to set disabled and checked instead of the .attr() method. The .val() method should be used for getting and setting value.

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

Important: the .removeProp() method should not be used to remove native properties. This will lead to unexpected behavior. See .removeProp() for more information.

Computed property values

By using a function to set properties, you can compute the value based on other properties of the element. For example, to toggle all checkboxes based off their individual values:

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

Note: If nothing is returned in the setter function (ie. function( index, prop ){}), or if undefined is returned, the current value is not changed. This is useful for selectively setting values only when certain criteria are met.

Disable all checkboxes on the page.

JS
<input type="checkbox" checked="checked" />
<input type="checkbox" />
<input type="checkbox" />
<input type="checkbox" checked="checked" />
CSS
img {
  padding: 10px;
}
div {
  color: red;
  font-size: 24px;
}
HTML
$("input[type='checkbox']").prop({
  disabled: true,
});
DEMO

Looking for a Web Developer?

👋

Hi! I'm Basti, author of this site. If you are looking for a web developer with 15+ years of experience, holla at me!

Be it the good 'ol jQuery, vanilla JS or modern frameworks like Vue and Svelte, front- or backend, I can help you.

Just write me at jobs@jqapi.com :)