Window: pageYOffset property

The read-only Window property pageYOffset is an alias for scrollY; as such, it returns the number of pixels the document is currently scrolled along the vertical axis (that is, up or down) with a value of 0.0, indicating that the top edge of the Document is currently aligned with the top edge of the window's content area.

There is slightly better support for pageYOffset than for scrollY in older browsers, but if you're not concerned about browsers more than a handful of years old, you can use either one.

The corresponding pageXOffset property, which returns the number of pixels scrolled along the horizontal axis (left and right), is an alias for scrollX.

Value

A double-precision floating-point number specifying the number of pixels the Document is scrolled vertically within its containing Window. This number is subpixel precise with a range of E(min)=-1022 to E(max)=1023, so it may not be an integer. A value of 0.0 indicates that the window is not scrolled vertically, and that the top of the document is located at the top edge of the window's content area.

Since this property is an alias for Window.scrollY, see that article for additional details on this value and its use.

Examples

In this example, an <iframe> is created and filled with content, then a specific element within the document is scrolled into view in the frame. Once that's done, the vertical scroll position is checked by looking at the value of pageYOffset in the frame's contentWindow.

HTML

The HTML is extremely simple and has just two elements: an <iframe> that contains the document we're going to scroll, and a <div> into which we'll output the value of pageYOffset when we've finished the scroll.

html

<iframe id="frame"> </iframe>

<div id="info"></div>

JavaScript

js

const frame = document.getElementById("frame");
const frameDoc = frame.contentDocument;
const info = document.getElementById("info");

const target = frameDoc.getElementById("overview");
frameDoc.scrollingElement.scrollTop = target.offsetTop;

info.innerText = `Y offset after scrolling: ${frame.contentWindow.pageYOffset} pixels`;

The JavaScript code begins by getting into frame and info the <iframe> element that contains our content as well as the <div> element into which we'll output the result of our scroll position check. It then gets a reference to the element we want to scroll into view calling getElementById() on the frame's HTMLIFrameElement.contentDocument.

With the target element in hand, we set the scrollTop of the frame's scrollingElement to the offsetTop of the target element. By doing so, we set the vertical scrolling position of the frame's document so that it's the same as the top edge of the target element.

This will automatically set the scrolling position to the maximum possible value if the attempted scroll would exceed the maximum. This prevents us from falling off the edge of the document. Nobody wants to know what's out there. There might be dragons.

Result

The result follows. Note that the frame's contents have been scrolled to show the section named "Overview", and that the value of the pageYOffset property is shown with the corresponding value.

Specifications

Specification
CSSOM View Module
# dom-window-pageyoffset

Browser compatibility

BCD tables only load in the browser

See also