JavaScript Element scrollBy() Method

What You’ll Learn

Element.scrollBy() is an instance method from the CSSOM View module. It scrolls an element by a given amount relative to where it is now. Learn delta scrolling, behavior: "smooth", the Promise interrupted flag, and five try-it labs.

Introduction

Carousels, image galleries, and long panels often need a small nudge—not a jump to pixel 1000. Call scrollBy() to move relative to the current scroll position by a number of pixels.

MDN: scrollBy(x, y) adds to the current offset. Like scroll(), modern browsers return a Promise with { interrupted } so you can run code when a smooth scroll finishes (or was cut short).

This page is part of JavaScript Element. Related: scroll(), scrollTop, and the JavaScript hub.

Understanding the scrollBy() Method

Calling el.scrollBy(x, y) or el.scrollBy({ top, left, behavior }) adds the given pixel amounts to the element’s current scroll offset.

• It is an instance method on Element (CSSOM View).
• Scrolls relative to the current position (MDN).
• Returns a Promise with { interrupted: boolean } (MDN).
• Options: top, left, behavior (smooth, instant, auto).
• Negative deltas scroll up or left; positive scroll down or right.
• Pair with scroll() when you need absolute coordinates.

📝 Syntax

General forms of Element.scrollBy (MDN):

scrollBy(xCoord, yCoord)
scrollBy(options)

Parameters

• xCoord, yCoord — horizontal and vertical pixels to scroll by (MDN).
• options (object):
  • top — Y-axis delta in pixels
  • left — X-axis delta in pixels
  • behavior — "smooth", "instant", or "auto" (default)

Return value

A Promise that fulfills with { interrupted: boolean } (MDN).

Exceptions

• No standard exceptions documented; invalid targets may simply not scroll.

Common patterns

const panel = document.getElementById("panel");

panel.scrollBy(0, 200);                   // MDN: nudge down 200px
panel.scrollBy({ top: 100, left: 50, behavior: "smooth" });

const result = await panel.scrollBy(0, -100);
console.log(result.interrupted);          // false if scroll finished

Examples Gallery

Examples follow MDN Element.scrollBy() patterns. Use View Output or Try It Yourself for each case.

const element = document.getElementById("panel");

// Scroll 300px right and 300px down from here
element.scrollBy(300, 300);

scrollTop and scrollLeft increase by 300 (if content allows).

element.scrollBy({
  top: 100,
  left: 100,
  behavior: "smooth",
});

Animated scroll by top: 100, left: 100.

document.querySelector(".scroll-by").addEventListener("click", async () => {
  const section = document.querySelector("section");
  const result = await section.scrollBy(0, 200);
  console.log("interrupted:", result.interrupted);
});

interrupted: false  (section scrollTop += 200)

async function nudgeAndReport(el, dy) {
  const result = await el.scrollBy({ top: dy, behavior: "smooth" });
  console.log(result.interrupted ? "Interrupted" : "Finished");
}

Finished  (or "Interrupted" if another scroll starts)

const track = document.getElementById("carousel");

document.getElementById("next").addEventListener("click", () => {
  track.scrollBy({ left: 200, behavior: "smooth" });
});

document.getElementById("prev").addEventListener("click", () => {
  track.scrollBy({ left: -200, behavior: "smooth" });
});

track.scrollLeft changes by ±200.

🚀 Common Use Cases

• Page-down / page-up buttons inside a scrollable panel.
• Carousel prev/next controls with scrollBy({ left }).
• Incremental reading apps that advance by one screen height.
• Animating small nudges with behavior: "smooth".
• Syncing UI after scroll completes via the Promise interrupted flag.
• Teaching absolute vs relative scrolling (scroll vs scrollBy).

📝 Notes

• Not Deprecated, Experimental, or Non-standard on MDN (Baseline Widely available since January 2020).
• scrollBy() scrolls relative to the current position (MDN).
• Returns a Promise with { interrupted: boolean } (MDN).
• Use scroll() for absolute positions; scrollBy() for deltas.
• behavior: "smooth" animates; pair with CSS scroll-behavior when using auto.
• Related: scroll(), scrollTop, scrollHeight, JavaScript hub.

💡 Best Practices