jQuery .position() Method

What You’ll Learn

The .position() method reads an element’s coordinates relative to its offset parent as a PlainObject { top, left } — ideal for layout inside positioned containers, aligning widgets near siblings, and keyboard nudging within a stage. This tutorial covers the getter-only API since jQuery 1.2, how to move elements with .css("top")/.css("left") when no setter exists, comparisons with .offset(), .css(), and getBoundingClientRect(), and practical measurement patterns.

Introduction

After learning document coordinates with .offset(), you often need placement inside a positioned wrapper — a modal panel, a game stage, or a relatively positioned sidebar. jQuery’s .position() returns a plain object with top and left pixel distances from the element’s offset parent, ready for local math without converting from page coordinates.

Available since jQuery 1.2, .position() is a getter with no arguments and no setter overload. It reads offset-parent coordinates from the first matched element only. Unlike .offset(), which always answers “where is this on the page?”, .position() answers “where is this inside its containing positioned element?” — more useful when positioning one element near another within the same DOM subtree.

If you have worked with native DOM APIs, remember that getBoundingClientRect() returns viewport-relative coordinates. jQuery’s .position() is neither document-relative nor viewport-relative — it is local to the offset parent’s padding box. For page-level placement or a built-in setter, use .offset() instead.

Understanding the .position() Method

Given a jQuery object, .position() returns the current offset-parent coordinates of the first matched element as a PlainObject { top, left }. Both values are numbers measured in pixels from the padding edge of the offset parent to the margin edge of the element.

Think of .position() as a local map inside a positioned container. .offset() is a GPS pin on the full page. Use .position() when aligning a tooltip arrow to a chip inside a panel, nudging a draggable box within a stage, or listing tile coordinates in a grid — anywhere offset-parent-relative placement matters.

📝 Syntax

jQuery .position() has one form — a getter with no arguments:

Get — no arguments (since 1.2)

.position()  // -> { top: Number, left: Number }

• Returns a PlainObject with top and left from the first matched element.
• Coordinates are relative to the offset parent (padding box of parent, margin box of element).
• Returns undefined when the jQuery set is empty.
• Values may be fractional on sub-pixel or zoomed layouts.
• Does not support hidden elements; does not account for margins on the html element.

How to move without a setter

Because .position() has no setter, reposition elements with explicit CSS:

// 1. Ensure the element is positioned
$el.css( "position", "absolute" );

// 2. Read current local coords, adjust, write back
var p = $el.position();
p.left += 10;
$el.css({ top: p.top, left: p.left });

• Set position: absolute or position: relative so top and left take effect.
• Read with .position(), mutate the numbers, write with .css({ top, left }).
• For document-level moves, use .offset({ top, left }) setter instead (since 1.4).

Return value

• Getter — PlainObject { top, left }. Empty set → undefined.
• No setter — passing arguments has no effect; jQuery does not provide .position({ top, left }).

Important note

Official jQuery API example

var p = $( "p" ).first();
var position = p.position();
$( "p" ).last().text( "left: " + position.left + ", top: " + position.top );

Examples Gallery

Example 1 follows the official jQuery API documentation inside a padded container. Examples 2–5 compare .position() with .offset(), log chip coords on click, move a box with arrow keys inside a stage, and enumerate grid tile positions. Use DevTools or the Try-it links to run each snippet.

var p = $( "p" ).first();
var position = p.position();
$( "p" ).last().text( "left: " + position.left + ", top: " + position.top );

left: ~20, top: ~20 (example — offset-parent coords of first <p>)
Getter returns PlainObject { top, left } from first matched element only
Values reflect padded div origin (padding box of offset parent)

var $box = $( "#box" );
var off = $box.offset();
var pos = $box.position();
$( "#out" ).html(
  ".offset()   → left: " + off.left + ", top: " + off.top + " (document)
" +
  ".position() → left: " + pos.left + ", top: " + pos.top + " (offset parent)"
);

.offset()   -> left: ~66, top: ~66 (document — includes wrap margin + padding)
.position() -> left: 0, top: 0 (inside #wrap offset parent)
Same element, two reference frames — pick the one your layout needs

$( "#panel .chip" ).on( "click", function() {
  var pos = $( this ).position();
  $( "#result" ).text(
    this.textContent + " position ( " + pos.left + ", " + pos.top + " )"
  );
});

Click Alpha -> Alpha position ( ~12, ~48 )
Click Beta  -> Beta position  ( ~72, ~48 )
Click Gamma -> Gamma position ( ~132, ~48 )
Coords are relative to #panel offset parent, not the document

var step = 10;
$( document ).on( "keydown", function( e ) {
  var $box = $( "#box" );
  var p = $box.position();
  if ( e.key === "ArrowLeft" )  p.left -= step;
  if ( e.key === "ArrowRight" ) p.left += step;
  if ( e.key === "ArrowUp" )    p.top  -= step;
  if ( e.key === "ArrowDown" )  p.top  += step;
  if ( /Arrow/.test( e.key ) ) {
    e.preventDefault();
    $box.css({ top: p.top, left: p.left });
  }
});

ArrowLeft  -> left decreases by 10px inside #stage
ArrowRight -> left increases by 10px inside #stage
ArrowUp    -> top decreases by 10px inside #stage
ArrowDown  -> top increases by 10px inside #stage
Read .position(), mutate p.left/p.top, write with .css({ top, left })

var lines = [];
$( "#grid .tile" ).each( function( i ) {
  var pos = $( this ).position();
  lines.push( "Tile " + ( i + 1 ) + ": left " + pos.left + ", top " + pos.top );
});
$( "#out" ).html( lines.join( "
" ) );

Tile 1: left 0, top 0
Tile 2: left 80, top 0
Tile 3: left 0, top 80
Tile 4: left 80, top 80
Each tile measured relative to #grid offset parent — useful for layout debugging

🚀 Common Use Cases

• Local click coordinate logging — $(this).position() on click to show where the user hit an element inside a panel.
• Tooltip and popover alignment — position overlays relative to a trigger’s .position() plus width/height inside the same container.
• In-container drag helpers — read .position(), update on mousemove, write with .css({ top, left }) (see Example 4).
• Keyboard nudging inside a stage — arrow-key handlers that increment/decrement local top and left without affecting document coords.
• Layout debugging — compare .position() and .offset() to trace offset-parent vs document mismatches.
• Grid and tile enumeration — loop tiles and log each .position() to verify flex or float layout (see Example 5).
• Relative widget placement — position one element near another within the same containing DOM element without scroll math.
• Animation starting points — capture local coords before .animate({ top, left }) for in-container motion paths.

📝 Notes

• Getter available since jQuery 1.2 — no arguments, no setter, no callback.
• Getter returns PlainObject { top, left } from the first matched element only.
• Coordinates are offset-parent-relative, not document-relative (contrast .offset()).
• Measured from offset parent padding box to element margin box.
• Does not account for margins on the html element.
• Empty jQuery set → getter returns undefined.
• Does not support hidden (display:none) elements — readings are unreliable.
• Values can be fractional (e.g. 82.5) on sub-pixel or zoomed displays; zoom may affect accuracy.
• To move elements, set position in CSS and use .css("top") / .css("left").

💡 Best Practices