JavaScript Window scrollBy() Method

What You’ll Learn

The scrollBy() method moves the page (or a scrollable element) by a relative pixel offset. This tutorial covers syntax, smooth scrolling, positive and negative values, how it differs from scrollTo(), reading scrollX / scrollY, five examples, and common UI patterns.

Introduction

Long pages need navigation—back-to-top buttons, “next section” controls, carousels, and horizontal galleries. The window.scrollBy() method lets JavaScript nudge the viewport by a number of pixels from wherever the user currently is.

Unlike moveBy() or resizeBy(), scrolling the document is allowed on normal tabs. Users still control the scrollbar and touch gestures; your script adds programmatic movement on top.

Understanding the scrollBy() Method

window.scrollBy(deltaX, deltaY) adds pixels to the current scroll position. Positive deltaX moves content left (you see more to the right); positive deltaY scrolls down. The method returns undefined.

Modern browsers also accept a ScrollToOptions object: scrollBy({ top: 300, left: 0, behavior: "smooth" }). Use top / left instead of positional arguments when you want smooth animation.

📝 Syntax

General forms of Window.scrollBy():

window.scrollBy(deltaX, deltaY);

// smooth relative scroll (ScrollToOptions):
window.scrollBy({ top: 300, behavior: "smooth" });

// shorthand (same in browsers):
scrollBy(0, 200);

Parameters

• deltaX (positional form) — horizontal pixels to scroll. Positive = right; negative = left.
• deltaY (positional form) — vertical pixels to scroll. Positive = down; negative = up.
• options (object form) — { top, left, behavior } where behavior is "auto" or "smooth".

Return value

• undefined.

Related APIs

• window.scrollTo(x, y) — scroll to absolute document coordinates.
• window.scrollX / scrollY — current horizontal and vertical scroll offset.
• element.scrollIntoView() — scroll so an element is visible.
• element.scrollBy() — relative scroll inside a scrollable container.
• window.innerHeight — viewport height; useful for “one screen down” steps.

Examples Gallery

Use the Try-it links on pages with enough content to scroll. Each example nudges the viewport by a relative offset.

window.scrollBy(0, 200);
console.log("Scrolled down 200px. scrollY =", window.scrollY);

Scrolled down 200px. scrollY = 200
(value depends on starting position)

document.getElementById("nextBtn").addEventListener("click", function () {
  window.scrollBy({
    top: window.innerHeight,
    behavior: "smooth"
  });
});

Click Next → page animates down by one viewport height.

window.scrollBy(0, -150);
console.log("Scrolled up 150px. scrollY =", window.scrollY);

Scrolled up 150px. scrollY = (previous − 150, min 0)

document.getElementById("gallery").scrollBy({
  left: 250,
  behavior: "smooth"
});

Gallery shifts 250px to the left (reveals content on the right).

const before = window.scrollY;
window.scrollBy(0, 100);
const after = window.scrollY;

console.log(`Before: ${before}px`);
console.log(`After:  ${after}px`);

Before: 0px
After:  100px

🚀 Common Use Cases

• Next / Previous section — step through full-page layouts.
• Back to top (small nudge) — or use scrollTo(0, 0) for instant top.
• Horizontal carousels — container.scrollBy({ left: 200, behavior: "smooth" }).
• Keyboard-style controls — arrow buttons that scroll fixed pixel steps.
• Tutorial walkthroughs — reveal content below the fold on demand.
• Reading position tweaks — fine adjustments after layout changes.

📝 Notes

• Scrolling past document edges is silently clamped—no error is thrown.
• For anchor links, CSS scroll-behavior: smooth on html can replace JavaScript for simple hash navigation.
• Detecting “near bottom” for infinite scroll uses the scroll event and scrollY, not repeated scrollBy calls.
• Respect prefers-reduced-motion—skip smooth scrolling when users request reduced motion.
• scrollBy on window scrolls the document; on an element it scrolls that element’s overflow area.
• To scroll to a specific heading, prefer element.scrollIntoView({ behavior: "smooth" }).

💡 Best Practices