Query - Dimensions API reference for Query methods related to element dimensions and positioning maximize-2 API Reference
Categories

Query - Dimensions

Get and set element dimensions, scroll positions, and natural sizes.

width

Gets or sets the width of elements.

Syntax

Get

$('selector').width()

Set

$('selector').width(value)

Parameters

NameTypeDescription
valuenumber/stringThe width to set for the element(s)

Returns

Get

  • Single Element - The width of that element in pixels.
  • Multiple Elements - An array of widths, one for each matched element.

Set

Query object (for chaining).

Usage

// Get width
const width = $('#myElement').width();
// Set width
$('#myElement').width(200);

Example

height

Gets or sets the height of elements.

Syntax

Get

$('selector').height()

Set

$('selector').height(value)

Parameters

NameTypeDescription
valuenumber/stringThe height to set for the element(s)

Returns

Get

  • Single Element - The height of that element in pixels.
  • Multiple Elements - An array of heights, one for each matched element.

Set

Query object (for chaining).

Usage

// Get height
const height = $('#myElement').height();
// Set height
$('#myElement').height(150);

Example

scrollTop

Gets or sets the vertical scroll position of elements.

Syntax

Get

$('selector').scrollTop()

Set

$('selector').scrollTop(value)

Parameters

NameTypeDescription
valuenumberThe vertical scroll position to set in pixels

Returns

Get

  • Single Element - The vertical scroll position of that element in pixels.
  • Multiple Elements - An array of vertical scroll positions, one for each matched element.

Set

Query object (for chaining).

Usage

// Get scroll position
const scrollPosition = $('.scrollable-div').scrollTop();
// Set scroll position
$('.scrollable-div').scrollTop(100);

Example

scrollLeft

Gets or sets the horizontal scroll position of elements.

Syntax

Get

$('selector').scrollLeft()

Set

$('selector').scrollLeft(value)

Parameters

NameTypeDescription
valuenumberThe horizontal scroll position to set in pixels

Returns

Get

  • Single Element - The horizontal scroll position of that element in pixels.
  • Multiple Elements - An array of horizontal scroll positions, one for each matched element.

Set

Query object (for chaining).

Usage

// Get scroll position
const scrollPosition = $('.scrollable-div').scrollLeft();
// Set scroll position
$('.scrollable-div').scrollLeft(50);

Example

naturalWidth

Gets the natural width of an element, including images and other HTML elements.

Performance Note: Creates an off-screen clone to measure dimensions. Can cause reflow - use sparingly in performance-critical code.

Syntax

Get

$('selector').naturalWidth()

Returns

Get

  • Single Element - The natural width of the element in pixels.
  • Multiple Elements - An array of natural widths, one for each matched element.

Usage

// Get natural width of image
const imageWidth = $('img').naturalWidth();
// Get natural width of table
const tableWidth = $('table').naturalWidth();

Example

naturalHeight

Gets the natural height of an element, including images and other HTML elements.

Syntax

Get

$('selector').naturalHeight()

Returns

Get

  • Single Element - The natural height of the element in pixels.
  • Multiple Elements - An array of natural heights, one for each matched element.

Usage

// Get natural height of image
const imageHeight = $('img').naturalHeight();
// Get natural height of div
const divHeight = $('div.content').naturalHeight();

Example

position

Gets or sets element position coordinates with flexible reference systems.

Syntax

Get Position (All Coordinates)

$('selector').position()
$('selector').position({ relativeTo: container, precision: 'pixel' })

Get Position (Specific Type)

$('selector').position({ type: 'global' })
$('selector').position({ type: 'local' })
$('selector').position({ type: 'relative', relativeTo: container })

Set Position

$('selector').position({ top: 100, left: 200 })
$('selector').position({ top: 50, left: 75, relativeTo: container })

Parameters

NameTypeDescription
relativeTostring/Element/QueryElement to measure relative to (for getter/setter)
topnumberTop position to set (triggers setter)
leftnumberLeft position to set (triggers setter)
precision’pixel’|‘subpixel’Rounding precision for coordinates. Defaults to ‘pixel’
type’global’|‘local’|‘relative’Specific coordinate system to return

Returns

Get Position (Default)

Returns an object with multiple coordinate systems:

  • Single Element - { global: {top, left}, local: {top, left}, relative?: {top, left} }
  • Multiple Elements - Array of position objects

Get Position (With Type)

  • Single Element - { top: number, left: number }
  • Multiple Elements - Array of coordinate objects

Set Position

Query object (for chaining).

Usage

// Get all position coordinates
const pos = $('#element').position();
console.log(pos.global.top, pos.local.left);
// Get only viewport coordinates
const viewport = $('#element').position({ type: 'global' });
// Get position relative to container
const relative = $('#element').position({
type: 'relative',
relativeTo: '#container'
});
// Set position relative to containing parent
$('#element').position({ top: 100, left: 200 });
// Set position relative to specific element
$('#element').position({
top: 50,
left: 75,
relativeTo: '#reference'
});

Coordinate Systems

  • Global: Position relative to viewport (window)
  • Local: Position relative to containing parent (positioned ancestor)
  • Relative: Position relative to specified element

Example

pagePosition

Gets element position relative to the document (viewport position + scroll offset).

Syntax

Get

$('selector').pagePosition()
$('selector').pagePosition({ precision: 'subpixel' })

Parameters

NameTypeDescription
precision’pixel’|‘subpixel’Rounding precision. Defaults to ‘pixel’

Returns

Get

  • Single Element - { top: number, left: number }
  • Multiple Elements - Array of position objects
  • Empty Selection - undefined

Usage

// Get page position
const pos = $('#element').pagePosition();
console.log(`Element is at ${pos.top}px from document top`);
// Get subpixel precision
const precisePos = $('#element').pagePosition({ precision: 'subpixel' });

Example

dimensions

Gets dimension information for elements.

Syntax

$('selector').dimensions()

Returns

  • Single Element - Dimension object
  • Multiple Elements - Array of dimension objects
  • Empty Selection - undefined

Properties

PropertyDescription
top, leftViewport position
right, bottomViewport edges
pageTop, pageLeftDocument position
widthContent width
innerWidthContent + padding
outerWidthContent + padding + border
marginWidthContent + padding + border + margin
heightContent height
innerHeightContent + padding
outerHeightContent + padding + border
marginHeightContent + padding + border + margin
scrollTop, scrollLeftScroll position
scrollHeight, scrollWidthScrollable dimensions
boxBox model details
boundsDOMRect bounding box

Usage

// Get all dimensions
const dims = $('#element').dimensions();
console.log(`Element size: ${dims.width}x${dims.height}`);
console.log(`With padding: ${dims.innerWidth}x${dims.innerHeight}`);
console.log(`With border: ${dims.outerWidth}x${dims.outerHeight}`);
console.log(`Page position: ${dims.pageTop}, ${dims.pageLeft}`);
// Access box model details
console.log(`Padding: ${dims.box.padding.top}px`);
console.log(`Border: ${dims.box.border.left}px`);
console.log(`Margin: ${dims.box.margin.bottom}px`);

Example

intersects

Checks if elements intersect with a target.

Syntax

$('selector').intersects(target)
$('selector').intersects(target, options)

Parameters

NameTypeDescription
targetstring/Element/QueryTarget element(s)
optionsobjectOptions (optional)

Options

NameTypeDescriptionDefault
sidesstring/arrayWhich sides must intersect (‘all’, ‘top’, ‘bottom’, ‘left’, ‘right’)‘all’
thresholdnumberMinimum intersection ratio (0-1)0
fullybooleanSource must be fully containedfalse
returnDetailsbooleanReturn detailed intersection datafalse
allbooleanWhether all elements must intersect (true) or any element (false)false

Returns

  • Basic - true if intersects, false otherwise
  • With returnDetails - Details object (single element) or array (multiple elements)

Details Object

PropertyTypeDescription
intersectsbooleanElements intersect
topbooleanTop edge within target
bottombooleanBottom edge within target
leftbooleanLeft edge within target
rightbooleanRight edge within target
rationumberIntersection/source area ratio
rectobjectIntersection rectangle (or null)
elementPositionobjectElement position relative to target

Usage

// Check intersection
if ($('#trigger').intersects('#popup')) {
console.log('Overlapping');
}
// Multiple targets
if ($('.item').intersects('.dropzone')) {
console.log('Over dropzone');
}
// 50% overlap required
$('#draggable').intersects('#target', { threshold: 0.5 });
// Must be fully contained
$('#child').intersects('#container', { fully: true });
// Check specific sides
$('#element').intersects('#boundary', { sides: 'top' });
$('#element').intersects('#boundary', { sides: ['left', 'right'] });
// Get detailed data
const details = $('#source').intersects('#target', { returnDetails: true });
if (details.intersects) {
console.log(`Overlap: ${details.ratio * 100}%`);
console.log(`Area: ${details.rect.width * details.rect.height}px²`);
console.log(`Element position relative to target:`, details.elementPosition);
}
// Require ALL elements to intersect
if ($('.items').intersects('#container', { all: true })) {
console.log('All items are within container');
}
// Multiple elements with position analysis
$('.item').intersects('#container', { returnDetails: true })
.forEach((details, i) => {
if (details.intersects) {
console.log(`Item ${i}: ${details.ratio * 100}% overlap`);
// Use elementPosition for obstruction analysis
const pos = details.elementPosition;
if (pos.top < 0) console.log(`Item ${i} extends above container`);
if (pos.bottom > targetDims.outerHeight) console.log(`Item ${i} extends below container`);
}
});

Notes

  • Uses outerWidth and outerHeight for box-model accuracy
  • Coordinates relative to target element
  • fully overrides threshold when true
  • With sides, at least one specified side must intersect
  • By default, returns true if ANY element intersects (use all: true to require all elements)
  • elementPosition provides element bounds relative to target for advanced positioning analysis

Example

Previous
CSS
Next
Display & Visibility