jQuery .offset() Method

What You’ll Learn

The .offset() method gets or sets an element’s coordinates relative to the document as a PlainObject { top, left } — ideal for tooltips, click tracking, and drag-and-drop at page level. This tutorial covers getter and setter overloads, comparisons with .position(), .css("top")/.css("left"), and getBoundingClientRect(), callback setters since 1.4, and practical keyboard-move patterns.

Introduction

After learning dimension methods like .height() and .innerWidth(), you often need to know where an element sits on the page — not just how big it is. jQuery’s .offset() returns a plain object with top and left pixel distances from the document origin, ready for math, logging, and repositioning without parsing CSS strings.

Available since jQuery 1.2 as a getter, .offset() gained setter and callback forms in jQuery 1.4. The getter reads document coordinates from the first matched element; the setter moves every matched element to new document coordinates. Unlike .position(), which is relative to the offset parent, .offset() always answers “where is this on the page?”

If you have worked with native DOM APIs, element.getBoundingClientRect() returns viewport-relative coordinates. To convert to document coords you add window.scrollX and window.scrollY. jQuery’s .offset() performs that style of calculation for you and wraps it in a familiar jQuery API with optional setter support.

Understanding the .offset() Method

Given a jQuery object, .offset() either returns the current document coordinates of the first matched element as a PlainObject { top, left } (getter), or repositions every matched element to the coordinates you pass (setter). Both values are numbers measured in pixels from the top-left corner of the document.

Think of .offset() as a GPS pin on the full page. .position() is a local map inside a positioned container. Use .offset() when placing overlays at click coordinates, aligning popovers to page landmarks, or moving draggable widgets with arrow keys — anywhere document-relative placement matters.

📝 Syntax

jQuery .offset() has three argument forms — one getter and two setters:

Get — no arguments (since 1.2)

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

• Returns a PlainObject with top and left from the first matched element.
• Coordinates are relative to the document, not the viewport or offset parent.
• Returns undefined when the jQuery set is empty.
• Values may be fractional on sub-pixel or zoomed layouts.

Set — coordinates object (since 1.4)

.offset( { top: value, left: value } )  // -> jQuery

• top / left — target document coordinates as Numbers (e.g. { top: 10, left: 30 }).
• Applies to every matched element; returns the original jQuery object for chaining.
• On position: static elements, jQuery sets position: relative before applying coordinates.

Set — callback function (since 1.4)

.offset( function( index, coords ) {
  // return new { top, left } object
} )

• index — zero-based position of the element in the matched set.
• coords — current { top, left } of this element before the change.
• Return a new coords object per element; jQuery applies it and returns the jQuery object.

$( ".tile" ).offset( function( index, coords ) {
  return {
    top: coords.top,
    left: coords.left + ( index * 24 )
  };
});

Each tile shifts 24px further right based on its index — useful for fan-out animations and grid corrections without manual loops.

Return value

• Getter — PlainObject { top, left }. Empty set → undefined.
• Setter — the original jQuery object for chaining.

Important note

Official jQuery API example

var p = $( "p" ).last();
var offset = p.offset();
p.html( "left: " + offset.left + ", top: " + offset.top );

Examples Gallery

Examples 1–3 follow the official jQuery API documentation. Examples 4–5 compare .offset() with .position() and build keyboard-driven movement. Use DevTools or the Try-it links to run each snippet.

var p = $( "p" ).last();
var offset = p.offset();
p.html( "left: " + offset.left + ", top: " + offset.top );

left: ~26, top: ~48 (example — document coords of last <p>)
Getter returns PlainObject { top, left } from first matched element only
Values reflect body padding and paragraph margin-left: 10px

$( "*", document.body ).on( "click", function( event ) {
  var offset = $( this ).offset();
  event.stopPropagation();
  $( "#result" ).text(
    this.tagName + " coords ( " + offset.left + ", " + offset.top + " )"
  );
});

Click P      -> P coords ( ~26, ~72 )
Click SPAN   -> SPAN coords ( ~26, ~96 )
Click green div -> DIV coords ( ~220, ~35 ) — position:absolute
stopPropagation() prevents parent handlers from overwriting #result

$( "p" ).last().offset({ top: 10, left: 30 });

Last paragraph jumps near top-left of document (10px from top, 30px from left)
Setter support arrived in jQuery 1.4
Static paragraphs get position:relative applied internally by jQuery

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

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

ArrowLeft  -> left decreases by 10px
ArrowRight -> left increases by 10px
ArrowUp    -> top decreases by 10px
ArrowDown  -> top increases by 10px
Read .offset(), mutate o.left/o.top, write with .offset(o)

🚀 Common Use Cases

• Click coordinate logging — $(this).offset() on click to show where the user hit an element on the page.
• Tooltip and popover placement — position overlays at document coords derived from a trigger’s .offset() plus width/height.
• Drag-and-drop helpers — read .offset(), update on mousemove, write with the setter (see Example 5).
• Keyboard nudging — arrow-key handlers that increment/decrement top and left in fixed steps.
• Layout debugging — compare .offset() and .position() to trace offset-parent vs document mismatches.
• Absolute repositioning — .offset({ top: 10, left: 30 }) to snap widgets to known document landmarks on load.
• Scroll-aware overlays — combine trigger .offset() with .outerHeight() / .outerWidth() to anchor menus below buttons.
• Staggered callback placement — .offset(function(i, c){ return { top: c.top + i * 20, left: c.left }; }) for cascaded panels.

📝 Notes

• Getter available since jQuery 1.2 — setter and callback since 1.4.
• Getter returns PlainObject { top, left } from the first matched element only.
• Coordinates are document-relative, not viewport-relative (contrast getBoundingClientRect()).
• Setter on position: static elements internally applies position: relative.
• .position() is offset-parent-relative and has no setter — do not confuse the two.
• Empty jQuery set → getter returns undefined.
• Unreliable on hidden (display:none) elements — may return { top: 0, left: 0 }.
• Values can be fractional (e.g. 82.5) on sub-pixel or zoomed displays.
• Setter returns the original jQuery object — e.g. .offset(o).addClass("moved").

💡 Best Practices