jQuery .outerWidth() Method

What You’ll Learn

The .outerWidth() method gets or sets the width of matched elements including padding and border as a unitless pixel Number — ideal when the full border box matters for layout math and horizontal row totals. This tutorial covers the optional includeMargin flag, getter and setter overloads, comparisons with .width(), .innerWidth(), and .outerHeight(), callback setters since 1.8, and practical row-sum patterns.

Introduction

After learning .innerWidth(), which measures content plus padding, you often need a dimension that also includes border — especially for fixed sidebars, horizontal card rows with margins, and subtracting one element’s full footprint from the viewport. jQuery’s .outerWidth() returns a plain number for the border box, ready for math and .animate() without parsing "96px" strings.

Available since jQuery 1.2.6 as a getter, .outerWidth() gained setter and callback forms in jQuery 1.8. Pass true as .outerWidth(true) to include horizontal margin in the measurement. Unlike .width(), it does not work on $(window) or $(document) — use it on DOM elements only.

Understanding the .outerWidth() Method

Given a jQuery object, .outerWidth() either returns the current width of the first matched element — content plus horizontal padding plus border — as a unitless pixel Number (getter), or sets the CSS width on every matched element so the outer box equals your value (setter). Margin is excluded by default; pass true to include it.

Think of .outerWidth() as a ruler that extends through padding and border. .width() stops at the content edge; .innerWidth() adds padding only; .outerWidth(true) continues through margin. Use .outerWidth() when subtracting a sidebar from the viewport or summing horizontal card rows — for example, available = $(window).width() - $("#sidebar").outerWidth().

📝 Syntax

jQuery .outerWidth() has four argument forms — one getter and three setters:

Get — optional includeMargin (since 1.2.6)

.outerWidth( [ includeMargin ] )  // -> Number

• includeMargin — optional Boolean. When true, horizontal margin is included in the returned width.
• Returns the width of the first matched element including padding and border as a unitless pixel Number.
• Margin excluded by default — pass true to add it.
• Not for $(window) or $(document) — elements only.
• Returns undefined when the jQuery set is empty.

Set — Number with optional includeMargin (since 1.8)

.outerWidth( value [, includeMargin ] )  // -> jQuery

• value — target outer width in pixels as a Number (e.g. 60).
• includeMargin — optional Boolean; when true, margin is factored into the CSS width calculation.
• jQuery adjusts the CSS width so content plus padding plus border (and optionally margin) equals the value.
• Returns the original jQuery object for chaining — e.g. .outerWidth(60).addClass("mod").

Set — callback function (since 1.8)

.outerWidth( function( index, width ) {
  // return new outer width (Number)
} )

• index — zero-based position of the element in the matched set.
• width — current outer width of this element before the change.
• Return a new outer width per element; jQuery applies it and returns the jQuery object.

Return value

• Getter — unitless Number (pixels). May be fractional on sub-pixel layouts. Empty set → undefined.
• Setter — the original jQuery object for chaining.

Important note

Official jQuery API example

var p = $( "p" ).first();
$( "#result" ).text(
  "outerWidth: " + p.outerWidth() +
  " , outerWidth(true): " + p.outerWidth( true )
);

Examples Gallery

Examples 1–2 follow the official jQuery API documentation. Examples 3–5 compare dimension methods, demonstrate callback setters, and sum horizontal card row widths with margin. Use DevTools or the Try-it links to run each snippet.

var p = $( "p" ).first();
$( "#result" ).text(
  "outerWidth: " + p.outerWidth() +
  " , outerWidth(true): " + p.outerWidth( true )
);

outerWidth: ~36px (content + padding + border)
outerWidth(true): ~56px (adds 10px left/right margin)
Getter returns unitless Number from first matched <p> only
Pass true to include horizontal margin in the count

var modWidth = 60;
$( "div" ).one( "click", function() {
  $( this ).outerWidth( modWidth ).addClass( "mod" );
  modWidth -= 8;
});

1st click -> outerWidth set to 60px, box turns blue (.mod)
2nd click -> outerWidth set to 52px
3rd -> 44px, 4th -> 36px, 5th -> 28px (modWidth -= 8 each time)
.one() ensures each box handler runs only once

var $box = $( "#box" );
var lines = [
  ".width()              → " + $box.width() + "px (content)",
  ".innerWidth()         → " + $box.innerWidth() + "px (+ padding)",
  ".outerWidth()         → " + $box.outerWidth() + "px (+ border)",
  ".outerWidth(true)     → " + $box.outerWidth( true ) + "px (+ margin)"
];
$( "#out" ).html( lines.join( "<br>" ) );

.width()              → ~24px (content only)
.innerWidth()         → ~48px (content + 12px padding left/right)
.outerWidth()         → ~56px (inner + 4px border left/right)
.outerWidth(true)     → ~88px (outer + 16px margin left/right)
Each step adds one layer of the CSS box model

function showVal() {
  $( "#val" ).text( $( "#panel" ).outerWidth() + "px" );
}
showVal();
$( "#panel" ).on( "click", function() {
  $( this ).outerWidth( function( index, width ) {
    return Math.max( 48, width - 12 );
  });
  showVal();
});

Initial outerWidth displayed in #val
Each click -> outerWidth decreases by 12px
Stops shrinking at 48px minimum (Math.max)
Callback receives current outer width before each change

var sum = 0;
$( ".card" ).each( function() {
  sum += $( this ).outerWidth( true );
});
$( "#total" ).text(
  "Total horizontal space (outerWidth with margin): " + sum + "px"
);

Card A, B, C each measured with .outerWidth(true)
Sum includes padding, border, and margin per card
Card B has extra padding and border — contributes more
Total displayed in #total for layout planning

🚀 Common Use Cases

• Viewport minus sidebar — available = $(window).width() - $("#sidebar").outerWidth() to size content beside a fixed sidebar.
• Horizontal row totals — sum .outerWidth(true) across cards to estimate total row width including margins.
• Equal column outer widths — read each column’s .outerWidth(), find the max, set all to match bordered columns.
• Shrink-on-click UI — callback setter .outerWidth(function(i, w){ return w - 12; }) for interactive panels.
• Dimension debugging — compare .width(), .innerWidth(), and .outerWidth() to trace box-model mismatches.
• Animation targets — pair measured .outerWidth() with .animate() when border must stay inside the animated box.

📝 Notes

• Getter available since jQuery 1.2.6 — setter and callback since 1.8.
• Getter returns a unitless pixel Number from the first matched element only.
• Includes horizontal padding and border — margin excluded unless true is passed.
• Not for $(window) or $(document) — use .width() on those instead.
• Empty jQuery set → getter returns undefined.
• Unreliable on hidden (display:none) elements — may return 0.
• On border-collapse: collapse tables, per-cell .outerWidth() may be inaccurate — measure the table or use getBoundingClientRect().
• Values can be fractional (e.g. 86.5) on sub-pixel or zoomed displays.
• Setter returns the original jQuery object — e.g. .outerWidth(60).addClass("mod").

💡 Best Practices