entries/width.xml

<?xml version="1.0"?>
<entries>
  <desc>Get the current computed width for the first element in the set of matched elements or set the width of every matched element.</desc>
  <entry type="method" name="width" return="Number">
    <title>.width()</title>
    <signature>
      <added>1.0</added>
    </signature>
    <desc>Get the current computed width for the first element in the set of matched elements.</desc>
    <longdesc>
      <p>The difference between <code>.css( "width" )</code> and <code>.width()</code> is that the latter returns a unit-less pixel value (for example, <code>400</code>) while the former returns a value with units intact (for example, <code>400px</code>). The <code>.width()</code> method is recommended when an element's width needs to be used in a mathematical calculation.</p>
      <figure>
        <img src="/resources/0042_04_04.png"/>
        <figcaption>Figure 1 - Illustration of the measured width</figcaption>
      </figure>
      <p>This method is also able to find the width of the window and document.</p>
      <pre><code>
// Returns width of browser viewport
$( window ).width();

// Returns width of HTML document
$( document ).width();
      </code></pre>
      <p>Note that <code>.width()</code> will always return the content width, regardless of the value of the CSS <code>box-sizing</code> property. As of jQuery 1.8, this may require retrieving the CSS width plus <code>box-sizing</code> property and then subtracting any potential border and padding on each element when the element has <code>box-sizing: border-box</code>. To avoid this penalty, use <code>.css( "width" )</code> rather than <code>.width()</code>.</p>
      <div class="warning">
        <p><strong>Note:</strong> Although <code>style</code> and <code>script</code> tags will report a value for <code>.width()</code> or <code>height()</code> when absolutely positioned and given <code>display:block</code>, it is strongly discouraged to call those methods on these tags. In addition to being a bad practice, the results may also prove unreliable.</p>
      </div>
    </longdesc>
    <note id="dimensions-number" type="additional" data-title=".width()"/>
    <note id="hidden-element-dimensions" type="additional" data-title=".width()"/>
    <example>
      <desc>Show various widths.  Note the values are from the iframe so might be smaller than you expected.  The yellow highlight shows the iframe body.</desc>
      <code><![CDATA[
function showWidth( ele, w ) {
  $( "div" ).text( "The width for the " + ele + " is " + w + "px." );
}
$( "#getp" ).on( "click", function() {
  showWidth( "paragraph", $( "p" ).width() );
} );
$( "#getd" ).on( "click", function() {
  showWidth( "document", $( document ).width() );
} );
$("#getw").on( "click", function() {
  showWidth( "window", $( window ).width() );
} );
]]></code>
      <css><![CDATA[
  body {
    background: yellow;
  }
  button {
    font-size: 12px;
    margin: 2px;
  }
  p {
    width: 150px;
    border: 1px red solid;
  }
  div {
    color: red;
    font-weight: bold;
  }
]]></css>
      <html><![CDATA[
<button id="getp">Get Paragraph Width</button>
<button id="getd">Get Document Width</button>
<button id="getw">Get Window Width</button>
<div>&nbsp;</div>
<p>
  Sample paragraph to test width
</p>
]]></html>
    </example>
    <category slug="css"/>
    <category slug="dimensions"/>
    <category slug="manipulation/style-properties"/>
    <category slug="version/1.0"/>
    <category slug="version/1.4.1"/>
  </entry>
  <entry type="method" name="width" return="jQuery">
    <signature>
      <added>1.0</added>
      <argument name="value">
        <type name="String"/>
        <type name="Number"/>
        <desc>An integer representing the number of pixels, or an integer along with an optional unit of measure appended (as a string).</desc>
      </argument>
    </signature>
    <signature>
      <added>1.4.1</added>
      <argument name="function" type="Function">
        <argument name="index" type="Integer" />
        <argument name="value" type="Integer" />
        <return>
          <type name="String"/>
          <type name="Number"/>
        </return>
        <desc>A function returning the width to set. Receives the index position of the element in the set and the old width as arguments. Within the function, <code>this</code> refers to the current element in the set.</desc>
      </argument>
    </signature>
    <desc>Set the CSS width of each element in the set of matched elements.</desc>
    <longdesc>
      <p>When calling <code>.width("value")</code>, the value can be either a string (number and unit) or a number. If only a number is provided for the value, jQuery assumes a pixel unit. If a string is provided, however, any valid CSS measurement may be used for the width (such as <code>100px</code>, <code>50%</code>, or <code>auto</code>). Note that in modern browsers, the CSS width property does not include padding, border, or margin, unless the <code>box-sizing</code> CSS property is used.</p>
      <p>If no explicit unit is specified (like "em" or "%") then "px" is assumed.</p>
      <p>Note that <code>.width("value")</code> sets the content width of the box regardless of the value of the CSS <code>box-sizing</code> property.</p>
    </longdesc>
    <example>
      <desc>Change the width of each div the first time it is clicked (and change its color).</desc>
      <code><![CDATA[
var modWidth = 50;
$( "div" ).one( "click", function() {
  $( this ).width( modWidth ).addClass( "mod" );
  modWidth -= 8;
});
]]></code>
      <css><![CDATA[
  div {
    width: 70px;
    height: 50px;
    float: left;
    margin: 5px;
    background: red;
    cursor: pointer;
  }
  .mod {
    background: blue;
    cursor: default;
  }
]]></css>
      <html><![CDATA[
<div>d</div>
<div>d</div>
<div>d</div>
<div>d</div>
<div>d</div>
]]></html>
    </example>
    <category slug="css"/>
    <category slug="dimensions"/>
    <category slug="manipulation/style-properties"/>
    <category slug="version/1.0"/>
    <category slug="version/1.4.1"/>
  </entry>
</entries>