jQuery API

.offset()

Categories: CSS | Offset | Manipulation > Style Properties
Contents:

.offset() Returns: Object

Description: Get the current coordinates of the first element in the set of matched elements, relative to the document.

  • version added: 1.2.offset()

The .offset() method allows us to retrieve the current position of an element relative to the document. Contrast this with .position(), which retrieves the current position relative to the offset parent. When positioning a new element on top of an existing one for global manipulation (in particular, for implementing drag-and-drop), .offset() is the more useful.

.offset() returns an object containing the properties top and left.

Note: jQuery does not support getting the offset coordinates of hidden elements.

Examples:

Example: Access the offset of the second paragraph: 

<!DOCTYPE html>
<html>
<head>
  <style>
p { margin-left:10px; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.min.js"></script>
</head>
<body>
	<p>Hello</p><p>2nd Paragraph</p>
<script>var p = $("p:last");
var offset = p.offset();
p.html( "left: " + offset.left + ", top: " + offset.top );</script>

</body>
</html>

Demo:

Example: Click to see the offset. 

<!DOCTYPE html>
<html>
<head>
  <style>
p { margin-left:10px; color:blue; width:200px; 
    cursor:pointer; }
span { color:red; cursor:pointer; }
div.abs { width:50px; height:50px; position:absolute;
          left:220px; top:35px; background-color:green; 
          cursor:pointer; }
  </style>
  <script src="http://code.jquery.com/jquery-latest.min.js"></script>
</head>
<body>
	<div id="result">Click an element.</div>
<p>
  This is the best way to <span>find</span> an offset.
</p>

<div class="abs">
</div>
  
<script>
$("*", document.body).click(function (e) {
  var offset = $(this).offset();
  e.stopPropagation();
  $("#result").text(this.tagName + " coords ( " + offset.left + ", " +
                                  offset.top + " )");
});

</script>

</body>
</html>

Demo:

.offset( coordinates ) Returns: jQuery

Description: Set the current coordinates of every element in the set of matched elements, relative to the document.

  • version added: 1.4.offset( coordinates )

    coordinatesAn object containing the properties top and left, which are integers indicating the new top and left coordinates for the elements.

  • version added: 1.4.offset( function(index, coords) )

    function(index, coords)A function to return the coordinates to set. Receives the index of the element in the collection as the first argument and the current coordinates as the second argument. The function should return an object with the new top and left properties.

The .offset() setter method allows us to reposition an element. The element's position is specified relative to the document. If the element's position style property is currently static, it will be set to relative to allow for this repositioning.

Example:

Set the offset of the second paragraph:

<!DOCTYPE html>
<html>
<head>
  <style>p { margin-left:10px; } </style>
  <script src="http://code.jquery.com/jquery-latest.min.js"></script>
</head>
<body>
	<p>Hello</p><p>2nd Paragraph</p>
<script>$("p:last").offset({ top: 10, left: 30 });</script>

</body>
</html>

Demo:

Comments

  • Support requests, bug reports, and off-topic comments will be deleted without warning.

  • Please do post corrections or additional examples for .offset() below. We aim to quickly move corrections into the documentation.
  • If you need help, post at the forums or in the #jquery IRC channel.
  • Report bugs on the bug tracker or the jQuery Forum.
  • Discussions about the API specifically should be addressed in the Developing jQuery Core forum.
  • Pablo Ziliani
    I was having trouble setting the position of a body's child element using offset() on IE (any version), I haven't delved much into it, but the effect was like it *sometimes* added some extra value to the left and to the top (the actually numbers were 1024 and 256, if I remember correctly... not sure if this has any further meaning).

    I managed to work it around using .css({top: $foo, left: $bar}), but it worked only because the body happens to be also the offset parent.
  • Cui Jiajun
    try to add below script
    $("p:last").offset(function(index,coords){
    alert(index);
    alert(coords.left);
    });
    ,IE simply raises Error such as "'top' is null or not an object"

    Don't know what's wrong
  • Earl Jenkins
    It's worth noting that, in IE only, if you only provide a "top" value for the offset, an error occurs. Consider this code:

    $('my_elem').offset({top: 100});

    In FF, Chrome and Safari, this does exactly what you expect: moves my_elem vertically to 100px from the top, without changing the horizontal positioning. In IE, this causes an error.

    As it turns out, IE looks at the undefined "left" value, and stringifies it to "NaN". This means that the jQuery offset() code tries to do something like this:

    my_elem.style.left = "NaNpx";

    Thus, the error.

    To resolve this problem, be sure to provide a "left" value in your offset() call. If you want to retain the current "left" value, you could do this:

    var my_elem_offset = $('my_elem').offset();

    my_elem_offset.top = 100;
    $('my_elem').offset(my_elem_offset);
  • Timothy Wall
    I don't see any mention of the defined behavior when .offset() is applied to an element within an iframe. I currently see (with 1.4.2) that the offset returned is relative to the containing iframe. Is the containing iframe considered the "document" in this case?
  • The offset returned is calculated relative to the document jQuery was loaded in. So if you ask for the offset of an element inside an iframe from the parent document, offset will return the combined offsets of both documents.
  • Once the position of an element has been changed with offset(coordinates), is there a way to "let go" of the element and put it back where it would naturally wind up?

    I'm working on something that dynamically repositions things. I'd like to be able to reset and then reapply the positioning when the window is resized.
  • Peter
    You could save the offset object by first calling it without any parameters, and then use that object to reset it.

    var myOffset = $('#elementId').offset();
    // reposition however you want, then reset by:
    $('#elementId').offset(myOffset);
  • yunchenge
    I try this just a moment, but I found that the top value is not correct, I got "800" for myOffset.top, but when I reset it, the top value is 500.
  • Peter
    I have noticed that it doesn't behave properly when you've changed the dimensions of the body element. For example, it wasn't behaving as expected when I had the css:

    body { width: 900px; }

    Once I removed this, and instead used a div to accomplish the same thing, it worked well.

    css:
    body>div { width: 900px; }

    html:
    <div>
    ...
    </div>
  • Since .offset(coords) sets the top and left style properties, you could probably "release" the positioning by doing something like this:
    $('myelement').css({top: '', left: ''});