Skip to content

Commit 78963ae

Browse files
timmywiltimmywil
committed
Update attributes vs properties documentation. Close gh-237.
1 parent d8f15ae commit 78963ae

File tree

2 files changed

+89
-4
lines changed

2 files changed

+89
-4
lines changed

‎entries/attr.xml‎

Lines changed: 84 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,6 @@
1212
<desc>Get the value of an attribute for the first element in the set of matched elements.</desc>
1313
<longdesc>
1414
<p>The <code>.attr()</code> method gets the attribute value for only the <em>first</em> element in the matched set. To get the value for each element individually, use a looping construct such as jQuery's <code>.each()</code> or <code>.map()</code> method.</p>
15-
<p><strong>As of jQuery 1.6</strong>, the <code>.attr()</code> method returns <code>undefined</code> for attributes that have not been set. In addition, <code>.attr()</code> should not be used on plain objects, arrays, the window, or the document. To retrieve and change DOM properties, use the <a href="http://api.jquery.com/prop/">.prop()</a> method.</p>
1615
<p>Using jQuery's <code>.attr()</code> method to get the value of an element's attribute has two main benefits:</p>
1716
<ol>
1817
<li><strong>Convenience</strong>: It can be called directly on a jQuery object and chained to other jQuery methods.</li>
@@ -21,7 +20,91 @@
2120
<blockquote>
2221
<p><strong>Note:</strong> Attribute values are strings with the exception of a few attributes such as value and tabindex.</p>
2322
</blockquote>
23+
<p><strong>As of jQuery 1.6</strong>, the <code>.attr()</code> method returns <code>undefined</code> for attributes that have not been set. In addition, <code>.attr()</code> should not be used on plain objects, arrays, the window, or the document. To retrieve and change DOM properties, use the <a href="http://api.jquery.com/prop/">.prop()</a> method.</p>
24+
25+
<h4>Attributes vs. Properties</h4>
26+
<p>The difference between <em>attributes</em> and <em>properties</em> can be important in specific situations. <strong>Before jQuery 1.6</strong>, the <code>.attr()</code> method sometimes took property values into account when retrieving some attributes, which could cause inconsistent behavior. <strong>As of jQuery 1.6</strong>, the <code>.prop()</code> method provides a way to explicitly retrieve property values, while <code>.attr()</code> retrieves attributes.</p>
27+
<p>For example, <code>selectedIndex</code>, <code>tagName</code>, <code>nodeName</code>, <code>nodeType</code>, <code>ownerDocument</code>, <code>defaultChecked</code>, and <code>defaultSelected</code> should be retrieved and set with the <code><a href="http://api.jquery.com/prop/">.prop()</a></code> method. Prior to jQuery 1.6, these properties were retrievable with the <code>.attr()</code> method, but this was not within the scope of <code>attr</code>. These do not have corresponding attributes and are only properties.</p>
28+
<p>Concerning boolean attributes, consider a DOM element defined by the HTML markup <code>&lt;input type="checkbox" checked="checked" /&gt;</code>, and assume it is in a JavaScript variable named <code>elem</code>:</p>
29+
<table class="listing">
30+
<tr>
31+
<th>
32+
<code>elem.checked</code>
33+
</th>
34+
<td><code>true</code> (Boolean) Will change with checkbox state</td>
35+
</tr>
36+
<tr>
37+
<th>
38+
<code>$(elem).prop("checked")</code>
39+
</th>
40+
<td><code>true</code> (Boolean) Will change with checkbox state</td>
41+
</tr>
42+
<tr>
43+
<th>
44+
<code>elem.getAttribute("checked")</code>
45+
</th>
46+
<td><code>"checked"</code> (String) Initial state of the checkbox; does not change</td>
47+
</tr>
48+
<tr>
49+
<th>
50+
<code>$(elem).attr("checked")</code>
51+
<em>(1.6)</em>
52+
</th>
53+
<td><code>"checked"</code> (String) Initial state of the checkbox; does not change</td>
54+
</tr>
55+
<tr>
56+
<th>
57+
<code>$(elem).attr("checked")</code>
58+
<em>(1.6.1+)</em>
59+
</th>
60+
<td><code>"checked"</code> (String) Will change with checkbox state</td>
61+
</tr>
62+
<tr>
63+
<th>
64+
<code>$(elem).attr("checked")</code>
65+
<em>(pre-1.6)</em>
66+
</th>
67+
<td><code>true</code> (Boolean) Changed with checkbox state</td>
68+
</tr>
69+
</table>
70+
<br/>
71+
<p>According to the <a href="http://www.w3.org/TR/html401/interact/forms.html#h-17.4">W3C forms specification</a>, the <code>checked</code> attribute is a <em><a href="http://www.w3.org/TR/html4/intro/sgmltut.html#h-3.3.4.2">boolean attribute</a></em>, which means the corresponding property is <strong>true</strong> if the attribute is present at all&#x2014;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.</p>
72+
<p>Nevertheless, the most important concept to remember about the <code>checked</code> attribute is that it does not correspond to the <code>checked</code> property. The attribute actually corresponds to the <code>defaultChecked</code> property and should be used only to set the <em>initial</em> value of the checkbox. The <code>checked</code> attribute value does not change with the state of the checkbox, while the <code>checked</code> property does. Therefore, the cross-browser-compatible way to determine if a checkbox is checked is to use the property:</p>
73+
<ul>
74+
<li>
75+
<code>if ( elem.checked )</code>
76+
</li>
77+
<li>
78+
<code>if ( $(elem).prop("checked") )</code>
79+
</li>
80+
<li>
81+
<code>if ( $(elem).is(":checked") )</code>
82+
</li>
83+
</ul>
84+
<p>The same is true for other dynamic attributes, such as <code>selected</code> and <code>value</code>.</p>
2485
</longdesc>
86+
<note id="prop-memory-leaks" type="additional"/>
87+
<example>
88+
<desc>Display the checked attribute and property of a checkbox as it changes.</desc>
89+
<code><![CDATA[
90+
$("input").change(function() {
91+
var $input = $(this);
92+
$("p").html(".attr('checked'): <b>" + $input.attr('checked') + "</b><br>"
93+
+ ".prop('checked'): <b>" + $input.prop('checked') + "</b><br>"
94+
+ ".is(':checked'): <b>" + $input.is(':checked') ) + "</b>";
95+
}).change();
96+
]]></code>
97+
<css><![CDATA[
98+
p { margin: 20px 0 0 }
99+
b { color: blue; }
100+
]]></css>
101+
<html><![CDATA[
102+
<input id="check1" type="checkbox" checked="checked">
103+
<label for="check1">Check me</label>
104+
<p></p>
105+
]]></html>
106+
</example>
107+
<br/>
25108
<example>
26109
<desc>Find the title attribute of the first &lt;em&gt; in the page.</desc>
27110
<code><![CDATA[

‎entries/prop.xml‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@
1212
<desc>Get the value of a property for the first element in the set of matched elements.</desc>
1313
<longdesc>
1414
<p>The <code>.prop()</code> method gets the property value for only the <em>first</em> element in the matched set. It returns <code>undefined</code> 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 <code>.each()</code> or <code>.map()</code> method.</p>
15+
<h4>Attributes vs. Properties</h4>
1516
<p>The difference between <em>attributes</em> and <em>properties</em> can be important in specific situations. <strong>Before jQuery 1.6</strong>, the <code><a href="http://api.jquery.com/attr/">.attr()</a></code> method sometimes took property values into account when retrieving some attributes, which could cause inconsistent behavior. <strong>As of jQuery 1.6</strong>, the <code>.prop()</code> method provides a way to explicitly retrieve property values, while <code>.attr()</code> retrieves attributes.</p>
1617
<p>For example, <code>selectedIndex</code>, <code>tagName</code>, <code>nodeName</code>, <code>nodeType</code>, <code>ownerDocument</code>, <code>defaultChecked</code>, and <code>defaultSelected</code> should be retrieved and set with the <code>.prop()</code> method. Prior to jQuery 1.6, these properties were retrievable with the <code>.attr()</code> method, but this was not within the scope of <code>attr</code>. These do not have corresponding attributes and are only properties.</p>
1718
<p>Concerning boolean attributes, consider a DOM element defined by the HTML markup <code>&lt;input type="checkbox" checked="checked" /&gt;</code>, and assume it is in a JavaScript variable named <code>elem</code>:</p>
@@ -56,8 +57,9 @@
5657
<td><code>true</code> (Boolean) Changed with checkbox state</td>
5758
</tr>
5859
</table>
59-
<p>
60-
According to the <a href="http://www.w3.org/TR/html401/interact/forms.html#h-17.4">W3C forms specification</a>, the <code>checked</code> attribute is a <em><a href="http://www.w3.org/TR/html4/intro/sgmltut.html#h-3.3.4.2">boolean attribute</a></em>, which means the corresponding property is true if the attribute is present at all&#x2014;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:</p>
60+
<br/>
61+
<p>According to the <a href="http://www.w3.org/TR/html401/interact/forms.html#h-17.4">W3C forms specification</a>, the <code>checked</code> attribute is a <em><a href="http://www.w3.org/TR/html4/intro/sgmltut.html#h-3.3.4.2">boolean attribute</a></em>, which means the corresponding property is <strong>true</strong> if the attribute is present at all&#x2014;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.</p>
62+
<p>Nevertheless, the most important concept to remember about the <code>checked</code> attribute is that it does not correspond to the <code>checked</code> property. The attribute actually corresponds to the <code>defaultChecked</code> property and should be used only to set the <em>initial</em> value of the checkbox. The <code>checked</code> attribute value does not change with the state of the checkbox, while the <code>checked</code> property does. Therefore, the cross-browser-compatible way to determine if a checkbox is checked is to use the property:</p>
6163
<ul>
6264
<li>
6365
<code>if ( elem.checked )</code>
@@ -69,7 +71,7 @@ According to the <a href="http://www.w3.org/TR/html401/interact/forms.html#h-17.
6971
<code>if ( $(elem).is(":checked") )</code>
7072
</li>
7173
</ul>
72-
<p>If using jQuery 1.6, the code <code>if ( $(elem).attr("checked") )</code> will retrieve the actual content <em>attribute</em>, 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 <code>.attr()</code> 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 <code>.prop()</code>. 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.</p>
74+
<p>The same is true for other dynamic attributes, such as <code>selected</code> and <code>value</code>.</p>
7375
</longdesc>
7476
<note id="prop-memory-leaks" type="additional"/>
7577
<example>

0 commit comments

Comments
 (0)