entries/attr.xml

<?xml version="1.0"?>
<entries>
  <desc>Get the value of an attribute for the first element in the set of matched elements or set one or more attributes for every matched element.</desc>
  <entry type="method" name="attr" return="String">
    <title>.attr()</title>
    <signature>
      <added>1.0</added>
      <argument name="attributeName" type="String">
        <desc>The name of the attribute to get.</desc>
      </argument>
    </signature>
    <desc>Get the value of an attribute for the first element in the set of matched elements.</desc>
    <longdesc>
      <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>
      <p>Using jQuery's <code>.attr()</code> method to get the value of an element's attribute has two main benefits:</p>
      <ol>
        <li><strong>Convenience</strong>: It can be called directly on a jQuery object and chained to other jQuery methods.</li>
        <li><strong>Cross-browser consistency</strong>: The values of some attributes are reported inconsistently across browsers, and even across versions of a single browser. The <code>.attr()</code> method reduces such inconsistencies.</li>
      </ol>
      <div class="warning">
        <p><strong>Note:</strong> Attribute values are strings with the exception of a few attributes such as value and tabindex.</p>
      </div>
      <p>As of jQuery 1.6, the <code>.attr()</code> method returns <code>undefined</code> for attributes that have not been set. <strong>To retrieve and change DOM properties such as the <code>checked</code>, <code>selected</code>, or <code>disabled</code> state of form elements, use the <a href="/prop/">.prop()</a> method.</strong></p>
      <note id="svg-support" type="additional"/>

      <h4>Attributes vs. Properties</h4>
      <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>
      <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="/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>
      <p>Concerning boolean attributes, consider a DOM element defined by the HTML markup <code>&lt;input type="checkbox" checked="" /&gt;</code>, and assume it is in a JavaScript variable named <code>elem</code>:</p>
      <table>
        <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>""</code> (String) Initial state of the checkbox; does not change</td>
        </tr>
        <tr>
          <th>
            <code>$( elem ).attr( "checked" )</code>
            <em>(4.0+)</em>
          </th>
          <td><code>""</code> (String) Initial state of the checkbox; does not change</td>
        </tr>
        <tr>
          <th>
            <code>$( elem ).attr( "checked" )</code>
            <em>(1.6-3.x)</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>(pre-1.6)</em>
          </th>
          <td><code>true</code> (Boolean) Changed with checkbox state</td>
        </tr>
      </table>
      <br/>
      <p>According to the <a href="https://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="https://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>
      <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>
      <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>The same is true for other dynamic attributes, such as <code>selected</code> and <code>value</code>.</p>
    </longdesc>
    <note id="prop-memory-leaks" type="additional"/>
    <example>
      <desc>Display the checked attribute and property of a checkbox as it changes.</desc>
      <code><![CDATA[
$( "input" )
  .on( "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>" );
  } )
  .trigger( "change" );
]]></code>
      <css><![CDATA[
  p {
    margin: 20px 0 0;
  }
  b {
    color: blue;
  }
]]></css>
      <html><![CDATA[
<input id="check1" type="checkbox" checked="checked">
<label for="check1">Check me</label>
<p></p>
]]></html>
    </example>
    <br/>
    <example>
      <desc>Find the title attribute of the first &lt;em&gt; in the page.</desc>
      <code><![CDATA[
var title = $( "em" ).attr( "title" );
$( "div" ).text( title );
]]></code>
      <css><![CDATA[
  em {
    color: blue;
    font-weight: bold;
  }
  div {
    color: red;
  }
]]></css>
      <html><![CDATA[
<p>Once there was a <em title="huge, gigantic">large</em> dinosaur...</p>

The title of the emphasis is:<div></div>
]]></html>
    </example>
    <category slug="attributes"/>
    <category slug="manipulation/general-attributes"/>
    <category slug="version/1.0"/>
    <category slug="version/1.1"/>
    <category slug="version/1.6"/>
    <category slug="version/4.0"/>
  </entry>
  <entry type="method" name="attr" return="jQuery">
    <signature>
      <added>1.0</added>
      <argument name="attributeName" type="String">
        <desc>The name of the attribute to set.</desc>
      </argument>
      <argument name="value">
        <type name="String"/>
        <type name="Number"/>
        <type name="Null"/>
        <type name="Boolean"/>
        <desc>A value to set for the attribute. If <code>null</code>, the specified attribute will be removed (as in <a href="/removeAttr/"><code>.removeAttr()</code></a>). Non-ARIA attributes can also be removed by passing <code>false</code>.</desc>
      </argument>
    </signature>
    <signature>
      <added>1.0</added>
      <argument name="attributes" type="PlainObject">
        <desc>An object of attribute-value pairs to set.</desc>
      </argument>
    </signature>
    <signature>
      <added>1.1</added>
      <argument name="attributeName" type="String">
        <desc>The name of the attribute to set.</desc>
      </argument>
      <argument name="function" type="Function">
        <desc>A function returning the value to set. <code>this</code> is the current element. Receives the index position of the element in the set and the old attribute value as arguments.</desc>
        <argument name="index" type="Integer" />
        <argument name="attr" type="String" />
        <return>
          <type name="String"/>
          <type name="Number"/>
        </return>
      </argument>
    </signature>
    <desc>Set one or more attributes for the set of matched elements.</desc>
    <longdesc>
      <p>The <code>.attr()</code> method is a convenient way to set the value of attributes&#x2014;especially when setting multiple attributes or using values returned by a function. Consider the following image:</p>
      <pre><code>&lt;img id="greatphoto" src="brush-seller.jpg" alt="brush seller"&gt;</code></pre>
      <h4 id="setting-simple-attr">Setting a simple attribute</h4>
      <p>To change the <code>alt</code> attribute, simply pass the name of the attribute and its new value to the <code>.attr()</code> method:</p>
      <pre><code>
$( "#greatphoto" ).attr( "alt", "Beijing Brush Seller" );
      </code></pre>
      <p><em>Add</em> an attribute the same way:</p>
      <pre><code>
$( "#greatphoto" ).attr( "title", "Photo by Kelly Clark" );
      </code></pre>
      <h4 id="setting-several-attrs">Setting several attributes at once</h4>
      <p>To change the <code>alt</code> attribute and add the <code>title</code> attribute at the same time, pass both sets of names and values into the method at once using a plain JavaScript object. Each key-value pair in the object adds or modifies an attribute:</p>
      <pre><code>
$( "#greatphoto" ).attr({
  alt: "Beijing Brush Seller",
  title: "photo by Kelly Clark"
});
      </code></pre>
      <p>When setting multiple attributes, the quotes around attribute names are optional.</p>
      <h4 id="removing-attr">Removing an attribute</h4>
      <p>To remove an attribute, either call <code>.attr( name, null )</code> or use <a href="/removeAttr/"><code>.removeAttr( name )</code></a>. For non-ARIA attributes, in jQuery 4.0+ you can also call <code>.attr( name, false )</code>.</p>
      <div class="warning">
        <p><strong>Note:</strong> Because <a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA">ARIA</a> attributes frequently associate behavior with "false" values that differs from attribute absence, passing <code>false</code> as the value for an attribute whose name starts with <code>"aria-…"</code> will stringify that value to <code>"false"</code> rather than remove the attribute. To guarantee removal of an attribute, use the <code>.removeAttr()</code> method or provide <code>null</code> as the value to the <code>.attr()</code> setter.</p>
      </div>
      <p><strong>WARNING</strong>: When setting the 'class' attribute, you must always use quotes!</p>
      <div class="warning">
        <p><strong>Note:</strong> Attempting to change the <code>type</code> attribute on an <code>input</code> or <code>button</code> element created via <code>document.createElement()</code> will throw an exception on Internet Explorer 8 or older.</p>
      </div>
      <h4 id="computed-attr-values">Computed attribute values</h4>
      <p>By using a function to set attributes, you can compute the value based on other properties of the element. For example, to concatenate a new value with an existing value:</p>
      <pre><code>
$( "#greatphoto" ).attr( "title", function( i, val ) {
  return val + " - photo by Kelly Clark";
});
      </code></pre>
      <p>This use of a function to compute attribute values can be particularly useful when modifying the attributes of multiple elements at once.</p>
      <p><strong>Note: </strong>If nothing is returned in the setter function (ie. <code>function(index, attr){}</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>
    </longdesc>
    <example>
      <desc>Set some attributes for all &lt;img&gt;s in the page.</desc>
      <code><![CDATA[
$( "img" ).attr({
  src: "/resources/hat.gif",
  title: "jQuery",
  alt: "jQuery Logo"
});
$( "div" ).text( $( "img" ).attr( "alt" ) );
]]></code>
      <css><![CDATA[
  img {
    padding: 10px;
  }
  div {
    color: red;
    font-size: 24px;
  }
]]></css>
      <html><![CDATA[
<img>
<img>
<img>

<div><b>Attribute of Ajax</b></div>
]]></html>
    </example>
    <example>
      <desc>Set the id for divs based on the position in the page.</desc>
      <code><![CDATA[
$( "div" )
  .attr( "id", function( arr ) {
    return "div-id" + arr;
  })
  .each(function() {
    $( "span", this ).html( "(id = '<b>" + this.id + "</b>')" );
});
]]></code>
      <css><![CDATA[
  div {
    color: blue;
  }
  span {
    color: red;
  }
  b {
    font-weight: bolder;
  }
]]></css>
      <html><![CDATA[
<div>Zero-th <span></span></div>
<div>First <span></span></div>
<div>Second <span></span></div>
]]></html>
    </example>
    <example>
      <desc>Set the src attribute from title attribute on the image.</desc>
      <code><![CDATA[
$( "img" ).attr( "src", function() {
  return "/resources/" + this.title;
});
]]></code>
      <html><![CDATA[
<img title="hat.gif">
]]></html>
    </example>
    <category slug="attributes"/>
    <category slug="manipulation/general-attributes"/>
    <category slug="version/1.0"/>
    <category slug="version/1.1"/>
    <category slug="version/1.6"/>
    <category slug="version/4.0"/>
  </entry>
</entries>