.prop( propertyName )Returns: String
Description: Get the value of a property for the first element in the set of matched elements.
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.
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.checked | true (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") (1.6.1+) | "checked" (String) Will change with checkbox state |
$(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 an empty string value. The preferred cross-browser-compatible way to determine if a checkbox is checked is to check for a "truthy" value on the element's property using one of the following:
if ( elem.checked )
if ( $(elem).prop("checked") )
if ( $(elem).is(":checked") )
If using jQuery 1.6, the code if ( $(elem).attr("checked") )
will retrieve the actual content attribute, which does not change as the checkbox is checked and unchecked. It is meant only to store the default or initial value of the checked property. To maintain backwards compatability, the .attr()
method in jQuery 1.6.1+ will retrieve and update the property for you so no code for boolean attributes is required to be changed to .prop()
. Nevertheless, the preferred way to retrieve a checked value is with one of the options listed above. To see how this works in the latest jQuery, check/uncheck the checkbox in the example below.
Additional Notes:
- In Internet Explorer prior to version 9, using
.prop()
to set a DOM element property to anything other than a simple primitive value (number, string, or boolean) can cause memory leaks if the property is not removed (using.removeProp()
) before the DOM element is removed from the document. To safely set values on DOM objects without memory leaks, use.data()
.
Example:
Display the checked property and attribute of a checkbox as it changes.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
|