jQuery .scrollTop() Method

What You’ll Learn

The .scrollTop() method gets or sets the vertical scroll offset of matched elements as a unitless pixel Integer — ideal for page scroll, vertical panels, and back-to-top buttons. This tutorial covers getter and setter overloads, comparisons with .scrollLeft(), native element.scrollTop and window.pageYOffset, $(window).scrollTop() for page scroll, scroll event handling, read-modify-write button patterns, and animated vertical scrolling.

Introduction

After learning horizontal scroll with .scrollLeft(), the natural next step is vertical scroll. jQuery’s .scrollTop() returns a plain integer you can read, increment, or pass directly to .animate() — without parsing CSS strings.

Available since jQuery 1.2.6, .scrollTop() works as both a getter (no arguments) and a setter (pixel value). The getter reads the vertical scroll offset of the first matched element — how many pixels of content are hidden above the visible area. The setter scrolls every element in the set to that position. Unlike .scrollLeft(), which is mainly used on overflow containers, .scrollTop() also works on $(window) and $(document) for page-level scroll.

Understanding the .scrollTop() Method

Given a jQuery object, .scrollTop() either returns the current vertical scroll offset of the first matched element as a unitless pixel Integer (getter), or sets the scroll position on every matched element (setter). The value represents pixels of content hidden above the visible area — 0 when flush at the top or when the element is not scrollable.

Think of .scrollTop() as a vertical window into overflowing content. .scrollLeft() is the horizontal twin. Native element.scrollTop (or window.pageYOffset for the page) does the same at the DOM level; jQuery adds collection semantics and chaining. Use .css() for styling overflow — not for reading the current scroll offset.

📝 Syntax

jQuery .scrollTop() has two argument forms — one getter and one setter:

Get — no arguments (since 1.2.6)

.scrollTop()  // -> Integer

• Returns the vertical scroll offset of the first matched element as a unitless pixel Integer.
• Reports pixels hidden above — 0 at the top edge or when not scrollable.
• Native equivalent: element.scrollTop; for the page: window.pageYOffset.

Set — Number (since 1.2.6)

.scrollTop( value )  // -> jQuery

• value — vertical scroll position in pixels (e.g. 300).
• Applied to every matched element in the set — including $(window).
• Returns the original jQuery object for chaining — e.g. .scrollTop(300).css("borderColor", "green").

Animate — smooth scroll (since 1.2.6)

.animate({ scrollTop: value }, duration )

• Tweens the scroll offset over time — ideal for back-to-top buttons and feed panels.
• Read current position with .scrollTop(), compute target, then animate.
• Returns the jQuery object; use a completion callback for post-scroll actions.

Return value

• Getter — unitless Integer (pixels). May be 0 when not scrollable.
• Setter — the original jQuery object for chaining.

Important note

Official jQuery API example

var p = $( "p" ).first();
$( "p" ).last().text( "scrollTop:" + p.scrollTop() );

Examples Gallery

Examples 1–2 follow the official jQuery API documentation. Examples 3–5 handle scroll events, read-modify-write buttons, and animated back-to-top. Use DevTools or the Try-it links to run each snippet.

var p = $( "p" ).first();
$( "p" ).last().text( "scrollTop:" + p.scrollTop() );

scrollTop:0 (at top edge on load)
After scrolling down manually -> scrollTop:120 (example)
Getter returns Integer from first matched element only

$( "div.demo" ).scrollTop( 300 );

On load -> div.demo jumps to scrollTop 300
300px of content hidden above becomes visible below
Setter applies to every matched div.demo element

$( "#panel" ).on( "scroll", function() {
  $( "#out" ).text( "scrollTop: " + $( this ).scrollTop() );
});

On scroll -> "scrollTop: 0" at top edge
Drag scrollbar down -> "scrollTop: 85" (updates live)
At bottom -> max scrollTop (content height minus container height)
Use scroll event + .scrollTop() getter for progress indicators

var step = 50;
$( "#up" ).on( "click", function() {
  var $el = $( "#panel" );
  $el.scrollTop( $el.scrollTop() - step );
});
$( "#down" ).on( "click", function() {
  var $el = $( "#panel" );
  $el.scrollTop( $el.scrollTop() + step );
});

Down click -> scrollTop increases by 50px
Up click    -> scrollTop decreases by 50px
At top edge -> scrollTop stays 0 (cannot go negative)
Read current .scrollTop(), add/subtract step, write back with setter

$( "#feed" ).scrollTop( 400 );
$( "#topBtn" ).on( "click", function() {
  $( "#feed" ).stop().animate({ scrollTop: 0 }, 400 );
});

Panel starts at scrollTop 400 (mid-feed)
Click "Back to top" -> feed animates to scrollTop 0 over 400ms
.stop() prevents animation queue buildup on repeated clicks
Smooth back-to-top UX without CSS scroll-behavior

🚀 Common Use Cases

• Back-to-top buttons — .animate({ scrollTop: 0 }, duration) on $(window) or a scrollable panel.
• Page scroll position — $(window).scrollTop() for sticky headers, scroll-spy, and parallax triggers.
• Vertical panels and feeds — chat windows, comment threads, and notification lists.
• Custom up/down controls — read-modify-write with up/down buttons (see Example 4).
• Scroll progress indicators — scroll event + .scrollTop() to update a vertical progress bar.
• Infinite scroll and lazy load — detect when scrollTop + innerHeight nears content height to fetch more items.

📝 Notes

• Available since jQuery 1.2.6 — vertical scroll counterpart of .scrollLeft().
• Getter returns a unitless pixel Integer from the first matched element only.
• Setter applies to all matched elements and returns the jQuery object for chaining.
• Also works on $(window) and $(document) for page scroll — unlike .scrollLeft().
• Requires overflow-y: auto, scroll, or content taller than the container for meaningful values.
• Does not work on hidden (display:none) elements.
• 0 means at the top edge or not scrollable — check overflow before assuming.
• Animatable via .animate({ scrollTop: value }, duration).
• Native equivalent: element.scrollTop / window.pageYOffset — jQuery adds collection semantics.

💡 Best Practices