How the jQuery outerHeight Method Works

The jQuery outerHeight() method is a built-in dimension function that calculates the total vertical space an element occupies on a webpage. This article explains how the method functions, breaks down how it accounts for CSS properties like padding, borders, and margins, compares it to alternative height methods, and demonstrates how to read and set heights using code examples.

Understanding the Calculation

By default, the outerHeight() method retrieves the height of the first matched element in a jQuery collection, including its content height, internal padding (top and bottom), and borders (top and bottom).

Unlike pure CSS height or jQuery’s .height(), which measure only the inner content box (in standard W3C box models), outerHeight() offers a true reflection of the element's visual footprint on the screen.

The standard calculation is:

\[\text{outerHeight} = \text{Content Height} + \text{Padding Top/Bottom} + \text{Border Top/Bottom}\]

Syntax and Parameters

The method accepts a boolean parameter to determine whether external margins should be factored into the measurement:

$(selector).outerHeight([includeMargin]);

• includeMargin (Optional, Boolean):
  • false (Default): Includes content, padding, and borders.
  • true: Includes content, padding, borders, and margins (top and bottom).

Height Methods Comparison

To choose the right method for your layout calculations, consider how jQuery separates element dimensions:

• .height(): Measures content only.
• .innerHeight(): Measures content + padding.
• .outerHeight() / .outerHeight(false): Measures content + padding + border.
• .outerHeight(true): Measures content + padding + border + margin.

Code Example: Reading Heights

Consider an element with the following CSS styling:

.box {
  height: 200px;
  padding: 15px;
  border: 5px solid black;
  margin: 20px;
  box-sizing: content-box;
}

Using jQuery to inspect .box:

// Returns 200 (content only)
const contentH = $('.box').height();

// Returns 230 (200 content + 30 total padding)
const innerH = $('.box').innerHeight();

// Returns 240 (200 content + 30 padding + 10 total border)
const outerH = $('.box').outerHeight();

// Returns 280 (200 content + 30 padding + 10 border + 40 total margin)
const fullOuterH = $('.box').outerHeight(true);

Using outerHeight() as a Setter

Starting with jQuery version 1.8.0, outerHeight() can also be used as a setter to modify the height of matched elements:

$(selector).outerHeight(value);

When you pass a numeric value or a string with units (e.g., 300 or "300px"), jQuery automatically calculates the necessary CSS content height required to make the element’s final outer height match your specified target. It subtracts the existing padding and borders from your given value before applying the result to the element's CSS height property.

// Sets the element's overall outer height to 300px
$('.box').outerHeight(300);

If the element uses box-sizing: border-box, jQuery adjusts the underlying calculations accordingly so the final rendered element precisely matches the requested dimension.