entries/height.xml

<?xml version="1.0"?>
<entries>
  <desc>Get the current computed height for the first element in the set of matched elements or set the height of every matched element.</desc>
  <entry type="method" name="height" return="Number">
    <title>.height()</title>
    <signature>
      <added>1.0</added>
    </signature>
    <desc>Get the current computed height for the first element in the set of matched elements.</desc>
    <longdesc>
      <p>The difference between <code>.css( "height" )</code> and <code>.height()</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>.height()</code> method is recommended when an element's height needs to be used in a mathematical calculation.</p>
      <figure>
        <img src="/resources/0042_04_01.png"/>
        <figcaption>Figure 1 - Illustration of the measured height</figcaption>
      </figure>
      <p>This method is also able to find the height of the window and document.</p>
      <pre><code>
// Returns height of browser viewport
$( window ).height();

// Returns height of HTML document
$( document ).height();
      </code></pre>
      <p>Note that <code>.height()</code> will always return the content height, regardless of the value of the CSS <code>box-sizing</code> property. As of jQuery 1.8, this may require retrieving the CSS height 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( "height" )</code> rather than <code>.height()</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=".height()"/>
    <note id="hidden-element-dimensions" type="additional" data-title=".height()"/>
    <example>
      <desc>Show various heights.  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 showHeight( element, height ) {
  $( "div" ).text( "The height for the " + element + " is " + height + "px." );
}
$( "#getp" ).on( "click", function() {
  showHeight( "paragraph", $( "p" ).height() );
});
$( "#getd" ).on( "click", function() {
  showHeight( "document", $( document ).height() );
});
$( "#getw" ).on( "click", function() {
  showHeight( "window", $( window ).height() );
});
]]></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 Height</button>
<button id="getd">Get Document Height</button>
<button id="getw">Get Window Height</button>

<div>&nbsp;</div>
<p>
  Sample paragraph to test height
</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="height" return="jQuery">
    <signature>
      <added>1.0</added>
      <argument name="value">
        <desc>An integer representing the number of pixels, or an integer with an optional unit of measure appended (as a string).</desc>
        <type name="String"/>
        <type name="Number"/>
      </argument>
    </signature>
    <signature>
      <added>1.4.1</added>
      <argument name="function" type="Function">
        <argument name="index" type="Integer" />
        <argument name="height" type="Integer" />
        <return>
          <type name="String"/>
          <type name="Number"/>
        </return>
        <desc>A function returning the height to set. Receives the index position of the element in the set and the old height as arguments. Within the function, <code>this</code> refers to the current element in the set.</desc>
      </argument>
    </signature>
    <desc>Set the CSS height of every matched element.</desc>
    <longdesc>
      <p>When calling <code>.height(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, a valid CSS measurement must be provided for the height (such as <code>100px</code>, <code>50%</code>, or <code>auto</code>). Note that in modern browsers, the CSS height property does not include padding, border, or margin.</p>
      <p>If no explicit unit was specified (like 'em' or '%') then "px" is concatenated to the value.</p>
      <p>Note that <code>.height(value)</code> sets the content height of the box regardless of the value of the CSS <code>box-sizing</code> property.</p>
    </longdesc>
    <example>
      <desc>To set the height of each div on click to 30px plus a color change.</desc>
      <code><![CDATA[
$( "div" ).one( "click", function() {
  $( this ).height( 30 ).css({
    cursor: "auto",
    backgroundColor: "green"
  });
});
]]></code>
      <css><![CDATA[
  div {
    width: 50px;
    height: 70px;
    float: left;
    margin: 5px;
    background: rgb(255,140,0);
    cursor: pointer;
  }
]]></css>
      <html><![CDATA[
<div></div>
<div></div>
<div></div>
<div></div>
<div></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>