JavaScript Window scrollBy() Method

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

Definition

window.scrollBy() scrolls the document by the given amount from the current position (MDN). Pass (x, y) deltas or an options object with top, left, and behavior. For absolute coordinates, use scrollTo().

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

Syntax

Call window.scrollBy. Start with this line.

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

Built into the browser. Call window.scrollBy(...) (or the global scrollBy(...)) — no import required.

Library declarations
JavaScript
scrollBy(x, y) or 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 the document by a given amount from the current position.

JavaScript
window.scrollBy(0, 200);
console.log("scrollY:", window.scrollY);
Try It Yourself

How It Works

  1. Relative. Adds 200 to the current scrollY.
  2. x = 0. No horizontal move.
  3. Repeatable. Call again to move another 200.
  4. Clamp. The browser won’t scroll past the document edges.

Example 2 — Smooth Options Object

MDN options form with behavior: "smooth".

JavaScript
window.scrollBy({
  top: 100,
  left: 0,
  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. top / left. Prefer these names with options.
  4. Negatives. top: -100 scrolls up.

Example 3 — One Viewport Down

MDN basic usage: scroll down (or up) by one screen height.

JavaScript
// down one page
window.scrollBy(0, window.innerHeight);

// up one page
window.scrollBy(0, -window.innerHeight);
Try It Yourself

How It Works

  1. innerHeight. Visible viewport height in pixels.
  2. Down. Positive delta moves one screen forward.
  3. Up. Negative delta moves one screen back.
  4. Pattern. Great for “Next section” buttons.

Example 4 — Await the Promise

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

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

step();
Try It Yourself

How It Works

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

Example 5 — Log scrollY Before and After

Verify how far the page moved.

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

console.log("Before:", before);
console.log("After:", after);
Try It Yourself

How It Works

  1. Snapshot. Store scrollY before the call.
  2. Scroll. Add a relative delta.
  3. Compare. New scrollY should be about +100 (unless clamped).
  4. Smooth note. With behavior: "smooth", read again after animation if needed.
Compatibility

Browser Support

Window.scrollBy() is marked Baseline Widely available on MDN (since July 2015). It is not Deprecated, Experimental, or Non-standard. Promise return / interrupted may vary — feature-detect if you depend on it. Browser Window API — not a Node.js built-in.

✓ Baseline · Widely available

scrollBy()

Scroll the document by a relative delta across modern browsers.

99% Core tag support
Chrome Yes
Full support
Edge Yes
Full support
Firefox Yes
Full support
Safari Yes
Full support
Opera Yes
Full support
HTML element 100% supported

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

Frequently Asked Questions

It scrolls the document by a relative amount from the current position (MDN). Positive y scrolls down; negative y scrolls up. Positive x scrolls right; negative x scrolls left.
No. MDN marks Window.scrollBy() as Baseline Widely available (since July 2015). 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 window before the first finished. Feature-detect if you rely on the Promise.
scrollBy() adds a delta to where you are now. scrollTo() jumps to absolute document coordinates. Use scrollBy for “next step” controls; use scrollTo or scrollIntoView for a known target.
Optional string: smooth (animate), instant (jump), or auto (use the computed CSS scroll-behavior). Default is auto (MDN).
Yes. Use window.scrollBy(0, window.innerHeight) or scrollBy({ top: window.innerHeight, behavior: "smooth" }) for a full-screen step.

Next: scrollTo()

Jump to absolute document coordinates.

scrollTo() →

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)

10 people found this page helpful

JavaScript Window resizeTo() Method JavaScript Window scrollTo() Method