‹‹ my blogjQuery Dimensions Plugin 1.1

Overview

The dimensions plugin extends jQuery with dimension centric methods. It has been rigorously tested and gives accurate results cross-browser. Methods like width and height are extended by dimensions to enable you to get the width and height of both the window and the document. Methods like offset and position help you find the coordinates of an element on your page. Check out the rest of the dimensions API and see some code samples.

Three Flavors

Dimensions comes in three flavors: full (with comments), minified and packed. If you use the minified version along with HTTP Compression the file size will only be about 2k.

Dimensions Plugin API

Methods

• height
• innerHeight
• innerWidth
• offset
• offsetParent
• outerHeight
• outerWidth
• position
• scrollLeft
• scrollTop
• width

height

This is an extension of the core height method to enable it for the window and document objects as well as elements. When used on an element a value can be passed in to set the height. This method works for both visible and hidden elements.

Returns:

A number in pixels

Arguments:

value

A positive number representing the desired height. If just a number, 'px' will be added for you.

Chainable:

Yes, when a value is passed in.

Example:

$(window).height();

$(document).height();

$("#myElement").height();

$("#myElement").height(100);

innerHeight

Gets the inner height (excludes the border and includes the padding) for the first matched element. This method works for both visible and hidden elements.

Returns:

A number in pixels

Chainable:

No

Example:

$("#myElement").innerHeight();

innerWidth

Gets the inner width (excludes the border and includes the padding) for the first matched element. This method works for both visible and hidden elements.

Returns:

A number in pixels

Chainable:

No

Example:

$("#myElement").innerHeight();

offset

Gets the position of an element relative to the viewport. For accurate calculations make sure to use pixel values for margins, borders and padding. This method only works with visible elements.

Returns:

An object with top and left properties that are numbers that represent the offset in pixels. If the scroll option is true, two more properties are added: scrollTop and scrollLeft.

Arguments:

options

Settings to configure the way the offset is calculated.

margin (Boolean)

Should the margin of the element be included in the calculations? True by default.

border (Boolean)

Should the border of the element be included in the calculations? False by default.

padding (Boolean)

Should the padding of the element be included in the calculations? False by default.

scroll (Boolean)

Should the scroll offsets of the parent elements be included in the calculations? True by default.

lite (Boolean)

When true it will bypass the browser normalizations like when dealing with borders and margins on parent elements. This provides a nice boost in performance but at the price of accuracy. False by default.

relativeTo (HTML Element)

This should be a parent of the element and should have position (like absolute or relative). It will retrieve the offset relative to this parent element. By default it is the body element.

returnObject

An object to store the return value in, so as not to break the chain. If passed in the chain will not be broken and the result will be assigned to this object.

Chainable:

Yes, when an object is passed as the second argument.

Example:

$("#myElement").offset();

Results:

{ top: 100, left: 100, scrollTop: 10, scrollLeft: 10 }

Example:

$("#myElement").offset({ scroll: false });

Results:

{ top: 100, left: 100 }

Example:

var offset = {};
$("#myElement").offset({ scroll: false }, offset);
					

Results:

offset == { top: 100, left: 100 }

offsetParent

Returns a jQuery collection with the positioned parent of the first matched element. This is the first parent of the element that has position (as in relative or absolute). This method only works with visible elements.

Returns:

jQuery collection

Chainable:

Yes

Example:

$("#myElement").offsetParent();

outerHeight

Gets the offsetHeight (includes the border and padding by default) for the first matched element. This method works for both visible and hidden elements. The margin can be included by passing an options map with margin set to true. Optional margin option added in 1.1

Returns:

A number in pixels

Arguments:

options

Settings to configure the way the outer height is calculated.

margin (Boolean)

Should the margin of the element be included in the calculations? False by default.

Chainable:

No

Example:

$("#myElement").outerHeight();

Example:

$("#myElement").outerHeight({ margin: true });

outerWidth

Gets the offsetWidth (includes the border and padding by default) for the first matched element. This method works for both visible and hidden elements. The margin can be included by passing an options map with margin set to true. Optional margin option added in 1.1

Returns:

A number in pixels

Arguments:

options

Settings to configure the way the outer height is calculated.

margin (Boolean)

Should the margin of the element be included in the calculations? False by default.

Chainable:

No

Example:

$("#myElement").outerWidth();

Example:

$("#myElement").outerWidth({ margin: true });

position

Gets the top and left position of an element relative to its offset parent. For accurate calculations make sure to use pixel values for margins, borders and padding. This method only works with visible elements.

Returns:

An object with top and left properties that are numbers representing the offset in pixels.

Chainable:

Yes, when an object is passed as the second argument.

Example:

$("#myElement").position();

Results:

{ top: 10, left: 10 }

Example:

var position = {};
$("#myElement").position(position);
					

Results:

position == { top: 10, left: 10 }

scrollLeft

Acts as both a getter and a setter. When no value is passed in, it gets the scroll left offset of the first matched element. When a value is passed in, the scroll left offset is set to that value on all matched elements. This method works for both visible and hidden elements.

Returns:

A number in pixels

Arguments:

value

A positive number representing the desired scroll left offset.

Chainable:

Yes, when a value is passed in.

Example:

$("#myElement").scrollLeft(100);

Example:

$("#myElement").scrollLeft();

Results:

100

scrollTop

Acts as both a getter and a setter. When no value is passed in, it gets the scroll top offset of the first matched element. When a value is passed in, the scroll left offset is set to that value on all matched elements. This method works for both visible and hidden elements.

Returns:

A number in pixels

Arguments:

value

A positive number representing the desired scroll top offset.

Chainable:

Yes, when a value is passed in.

Example:

$("#myElement").scrollTop(100);

Example:

$("#myElement").scrollTop();

Results:

100

width

This is an extension of the core width method to enable it for the window and document objects as well as elements. When used on an element a value can be passed in to set the width. This method works for both visible and hidden elements.

Returns:

A number in pixels

Arguments:

value

A positive number representing the desired width. If just a number, 'px' will be added for you.

Chainable:

Yes, when a value is passed in.

Example:

$(window).width();

$(document).width();

$("#myElement").width();

$("#myElement").width(100);

Code Samples

Download

The latest release can be downloaded from the Dimensions project page.

Or you can live on the edge and just pull from SVN: http://jqueryjs.googlecode.com/svn/trunk/plugins/dimensions/

Support

Support for the Dimensions Plugin is available through the jQuery Mailing List. This is a very active list to which many jQuery developers and users subscribe.

You can also report a bug, request a feature, submit a patch or request support from the Dimensions project page.