JavaScript Element scrollBy() Method

Beginner
5 min read
Updated: Nov 2026
3 examples
Method
Decorative image with the word SCROLLBY

Definition

Element.scrollBy() scrolls an element by the given amount relative to its current position (MDN). Pass (x, y) deltas or an options object with top, left, and behavior. For absolute coordinates, use scroll() / scrollTo().

Pass the required arguments shown below. Check return values and browser support before you rely on the result.

Syntax

Call el.scrollBy. Start with this line.

JavaScript
el.scrollBy(x, y) or el.scrollBy(options)
CallWhat it does
el.scrollBy(x, y) or el.scrollBy(options)Primary signature.
el.scrollBy(...)Call with the arguments your case needs.

Built into the browser. Call scrollBy(...) on an Element — no import required.

Library declarations
JavaScript
el.scrollBy(x, y) or el.scrollBy(options)

Parameters

ParameterDescription
options.behaviorOptional. smooth, instant, or auto
Negative valuesOptional. Scroll up / left

Return Value

Return ValueDescription
*Promise<{ interrupted }> (support varies)

JavaScript Examples

Example 1 — Scroll by a Delta

MDN: scroll an element by a given amount from the current position.

JavaScript
const box = document.getElementById("box");

box.scrollBy(0, 200);
console.log("scrollTop:", box.scrollTop);
Try It Yourself

How It Works

  1. Relative. Adds 200 to the current scrollTop.
  2. Repeatable. Call again to move another 200.
  3. Confirm. Read scrollTop after the call.
  4. Clamp. The browser won’t scroll past the max.

Example 2 — Smooth Options Object

MDN options form with behavior: "smooth".

JavaScript
const box = document.getElementById("box");

box.scrollBy({
  top: 100,
  left: 100,
  behavior: "smooth",
});
Try It Yourself

How It Works

  1. Object form. Same relative scroll, clearer for options.
  2. smooth. Animates the delta over time.
  3. Both axes. top and left can combine.
  4. Negatives. top: -100 scrolls up.

Example 3 — Await the Promise

MDN: respond when a smooth relative scroll finishes; check interrupted.

JavaScript
const box = document.getElementById("box");

async function step() {
  const result = await box.scrollBy({
    top: 200,
    behavior: "smooth",
  });
  console.log("interrupted?", result.interrupted);
}

step();
Try It Yourself

How It Works

  1. Await finish. Useful for smooth “next page” buttons.
  2. interrupted. True if another programmatic scroll started first.
  3. Feature-detect. Test box.scrollBy(0, 0) instanceof Promise.
  4. Fallback. If no Promise, the scroll still runs — just no await.
Compatibility

Browser Support

Element.scrollBy() is Baseline Widely available (MDN, since January 2020). It is not Deprecated, Experimental, or Non-standard. Promise return / interrupted may vary — feature-detect if you depend on it.

✓ Baseline Widely available

Element.scrollBy()

Scroll an element by a relative delta. Pair with scroll/scrollTo for absolute jumps.

Baseline Widely available
Google Chrome Supported · Desktop & Mobile
Full support
Mozilla Firefox Supported · Desktop & Mobile
Full support
Apple Safari Supported · macOS & iOS
Full support
Microsoft Edge Supported · Chromium
Full support
Internet Explorer No native support · Use a polyfill
Polyfill
Opera Supported · Modern versions
Full support
Samsung Internet Supported · Android
Full support
Android WebView Supported · Modern WebView
Full support
scrollBy() Baseline

Bottom line: Safe for modern apps. Prefer options + behavior for smooth UX; detect Promise support before awaiting.

Frequently Asked Questions

It scrolls an element by the given amount relative to its current position (MDN). Pass x/y deltas or an options object with top, left, and behavior.
No. MDN marks Element.scrollBy() as Baseline Widely available (since January 2020). It is not Deprecated, Experimental, or Non-standard. Some parts (such as the Promise return) may vary by browser.
MDN documents a Promise that fulfills with { interrupted }. interrupted is true if another programmatic scroll started on the same element before the first finished. Feature-detect if you rely on the Promise.
scrollBy() adds a delta to the current scroll position. scroll() / scrollTo() jump to absolute coordinates inside the element.
Optional string: smooth (animate), instant (jump), or auto (use the element’s CSS scroll-behavior). Default is auto (MDN).
Yes. Use negative deltas, e.g. scrollBy(0, -40) or scrollBy({ top: -40 }).

Next: Element scrollIntoView()

Scroll ancestors so a target element becomes visible.

scrollIntoView() tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

11 people found this page helpful

JavaScript Element scroll() Method JavaScript Element scrollIntoView() Method