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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
|
<!DOCTYPE html>
<html lang='en'><head><meta http-equiv='content-type' content='text/html; charset=UTF-8' /></head><body>
<div class="entry-content">
<div class="entry-title roundTop">
<h1 class="jq-clearfix">.prop()</h1>
<div class="entry-meta jq-clearfix">
Categories:
<span class="category"><a href="http://api.jquery.com/category/attributes/" title="View all posts in Attributes">Attributes</a></span> | <span class="category"><a href="http://api.jquery.com/category/manipulation/" title="View all posts in Manipulation">Manipulation</a> > <a href="http://api.jquery.com/category/manipulation/general-attributes/" title="View all posts in General Attributes">General Attributes</a></span>
</div>
</div>
<div class="toc">
<h4><span>Contents:</span></h4>
<ul class="toc-list">
<li>
<a href="#prop1">prop( propertyName ) </a><ul><li>.prop( propertyName )
</li></ul>
</li>
<li>
<a href="#prop2">prop( propertyName , value ) </a><ul>
<li>.prop( propertyName, value )
</li>
<li>.prop( map )
</li>
<li>.prop( propertyName, function(index, oldPropertyValue) )
</li>
</ul>
</li>
</ul>
</div>
<div id="prop1" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">.prop( propertyName )</span> <span class="returns">Returns: <a class="return" href="http://api.jquery.com/Types/#String">String</a></span>
</h2>
<div class="jq-box roundBottom entry-details">
<p class="desc"><strong>Description: </strong>Get the value of a property for the first element in the set of matched elements.</p>
<ul class="signatures"><li class="signature" id="prop-propertyName">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.6/">1.6</a></span>.prop( propertyName )</h4>
<p class="arguement"><strong>propertyName</strong>The name of the property to get.</p>
</li></ul>
<div class="longdesc">
<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>
<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>
<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>
<p>Concerning boolean attributes, consider a DOM element defined by the HTML markup <code><input type="checkbox" checked="checked" /></code>, and assume it is in a JavaScript variable named <code>elem</code>:</p>
<table class="listing">
<tr>
<th><code>elem.checked</code></th>
<td>
<code>true</code> (Boolean) Will change with checkbox state</td>
</tr>
<tr>
<th><code>$(elem).prop("checked")</code></th>
<td>
<code>true</code> (Boolean) Will change with checkbox state</td>
</tr>
<tr>
<th><code>elem.getAttribute("checked")</code></th>
<td>
<code>"checked"</code> (String) Initial state of the checkbox; does not change</td>
</tr>
<tr>
<th>
<code>$(elem).attr("checked")</code><em>(1.6)</em>
</th>
<td>
<code>"checked"</code> (String) Initial state of the checkbox; does not change</td>
</tr>
<tr>
<th>
<code>$(elem).attr("checked")</code><em>(1.6.1+)</em>
</th>
<td>
<code>"checked"</code> (String) Will change with checkbox state</td>
</tr>
<tr>
<th>
<code>$(elem).attr("checked")</code><em>(pre-1.6)</em>
</th>
<td>
<code>true</code> (Boolean) Changed with checkbox state</td>
</tr>
</table>
<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 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:</p>
<ul>
<li><code>if ( elem.checked )</code></li>
<li><code>if ( $(elem).prop("checked") )</code></li>
<li><code>if ( $(elem).is(":checked") )</code></li>
</ul>
<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>
</div>
<h3 id="notes-0">Additional Notes:</h3>
<div class="longdesc"><ul><li>In Internet Explorer prior to version 9, using <code><a href="http://api.jquery.com/prop/">.prop()</a></code> 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 <a href="http://api.jquery.com/removeProp/"><code>.removeProp()</code></a>) before the DOM element is removed from the document. To safely set values on DOM objects without memory leaks, use <a href="http://api.jquery.com/data/"><code>.data()</code></a>.</li></ul></div>
<h3>Example:</h3>
<div class="entry-examples" id="entry-examples"><div id="example-0">
<h4><span class="desc">Display the checked property and attribute of a checkbox as it changes.</span></h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<style>
p { margin: 20px 0 0 }
b { color: blue; }
</style>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<input id="check1" type="checkbox" checked="checked">
<label for="check1">Check me</label>
<p></p>
<script>
$("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();
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div></div>
</div>
</div>
<div id="prop2" class="entry method">
<h2 class="jq-clearfix roundTop section-title">
<span class="name">.prop( propertyName, value )</span> <span class="returns">Returns: <a class="return" href="http://api.jquery.com/Types/#jQuery">jQuery</a></span>
</h2>
<div class="jq-box roundBottom entry-details">
<p class="desc"><strong>Description: </strong>Set one or more properties for the set of matched elements.</p>
<ul class="signatures">
<li class="signature" id="prop-propertyName-value">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.6/">1.6</a></span>.prop( propertyName, value )</h4>
<p class="arguement"><strong>propertyName</strong>The name of the property to set.</p>
<p class="arguement"><strong>value</strong>A value to set for the property.</p>
</li>
<li class="signature" id="prop-map">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.6/">1.6</a></span>.prop( map )</h4>
<p class="arguement"><strong>map</strong>A map of property-value pairs to set.</p>
</li>
<li class="signature" id="prop-propertyName-functionindex- oldPropertyValue">
<h4 class="name">
<span class="versionAdded">version added: <a href="/category/version/1.6/">1.6</a></span>.prop( propertyName, function(index, oldPropertyValue) )</h4>
<p class="arguement"><strong>propertyName</strong>The name of the property to set.</p>
<p class="arguement"><strong>function(index, oldPropertyValue)</strong>A 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 <code>this</code> refers to the current element.</p>
</li>
</ul>
<div class="longdesc">
<p>The <code>.prop()</code> 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 <code>selectedIndex</code>, <code>tagName</code>, <code>nodeName</code>, <code>nodeType</code>, <code>ownerDocument</code>, <code>defaultChecked</code>, or <code>defaultSelected</code>. Since jQuery 1.6, these properties can no longer be set with the <code>.attr()</code> method. They do not have corresponding attributes and are only properties.</p>
<p>Properties generally affect the dynamic state of a DOM element without changing the serialized HTML attribute. Examples include the <code>value</code> property of input elements, the <code>disabled</code> property of inputs and buttons, or the <code>checked</code> property of a checkbox. The <code>.prop()</code> method should be used to set disabled and checked instead of the <code><a href="http://api.jquery.com/attr">.attr()</a></code> method. The <code><a href="http://api.jquery.com/val">.val()</a></code> method should be used for getting and setting value.</p>
<pre>
$("input").prop("disabled", false);
$("input").prop("checked", true);
$("input").val("someValue");
</pre>
<p><strong>Important:</strong> the <code><a href="http://api.jquery.com/removeProp">.removeProp()</a></code> method should not be used to set these properties to false. Once a native property is removed, it cannot be added again. See <code><a href="http://api.jquery.com/removeProp">.removeProp()</a></code> for more information.</p>
<h4 id="computed-prop-values">Computed property values</h4>
<p>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:</p>
<pre>$("input[type='checkbox']").prop("checked", function( i, val ) {
return !val;
});</pre>
<p><strong>Note: </strong>If nothing is returned in the setter function (ie. <code>function(index, prop){})</code>, or if <code>undefined</code> is returned, the current value is not changed. This is useful for selectively setting values only when certain criteria are met.</p>
</div>
<h3 id="notes-1">Additional Notes:</h3>
<div class="longdesc"><ul><li>In Internet Explorer prior to version 9, using <code><a href="http://api.jquery.com/prop/">.prop()</a></code> 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 <a href="http://api.jquery.com/removeProp/"><code>.removeProp()</code></a>) before the DOM element is removed from the document. To safely set values on DOM objects without memory leaks, use <a href="http://api.jquery.com/data/"><code>.data()</code></a>.</li></ul></div>
<h3>Example:</h3>
<div class="entry-examples" id="entry-examples-1"><div id="example-1-0">
<h4><span class="desc">Disable all checkboxes on the page.</span></h4>
<pre class="prettyprint"><code class="example demo-code"><!DOCTYPE html>
<html>
<head>
<style>
img { padding:10px; }
div { color:red; font-size:24px; }
</style>
<script src="http://code.jquery.com/jquery-1.7rc2.js"></script>
</head>
<body>
<input type="checkbox" checked="checked" />
<input type="checkbox" />
<input type="checkbox" />
<input type="checkbox" checked="checked" />
<script>
$("input[type='checkbox']").prop({
disabled: true
});
</script>
</body>
</html></code></pre>
<h4>Demo:</h4>
<div class="demo code-demo"></div>
</div></div>
</div>
</div>
</div>
</body></html>
|
