Element: scroll() method

Syntax

scroll(xCoord, yCoord)
scroll(options)

Parameters

xCoord

The pixel along the horizontal axis of the element that you want displayed in the upper left.

yCoord

The pixel along the vertical axis of the element that you want displayed in the upper left.

options

An object containing the following properties:

top Optional

Specifies the number of pixels along the Y axis to scroll the window or element.

left Optional

Specifies the number of pixels along the X axis to scroll the window or element.

behavior Optional

Determines whether scrolling is instant or animates smoothly. This option is a string that must take one of the following values:

• smooth: The scrolling animates smoothly.
• instant: The scrolling happens instantly in a single jump.
• auto: The scroll behavior is determined by the computed value of the scroll-behavior CSS property on the element.

If omitted, behavior defaults to auto.

Return value

A Promise that fulfills with an object containing the following property:

interrupted

A boolean value indicating whether the scrolling operation was interrupted (true) or not (false). Such an interruption typically happens when a programmatic scroll is ongoing, and another programmatic scroll is initiated on the same element before the first one finishes.

Examples

Basic usage

// Put the 1000th vertical pixel at the top of the element
element.scroll(0, 1000);

Using options:

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

Responding to the end of the scroll

Our element methods demo (see source code) demonstrates how the promise return value of scroll() can be used to respond to the end of a scrolling operation. This technique is mostly useful in cases where the scrolling occurs smoothly over time (achieved by setting the behavior option to smooth, or by setting the scrolling element's scroll-behavior property to smooth).

HTML

Our HTML includes a <section> element containing several paragraphs of content and a <div> element toolbar containing <button> elements that trigger various scrolling operations on the <section>.

<div>
  <button class="scroll">scroll() to 1000</button>
  <button class="scrollto">scrollTo() top</button>
  <button class="scrollby">scrollBy() 200</button>
  <button class="scrollintoview">Scroll last &lt;p&gt; into view</button>
</div>

<section>...</section>

CSS

We give the <section> element a fixed height and an overflow-y value of scroll so that it scrolls vertically, and set its scroll-behavior property to smooth so that any scroll operations are animated smoothly over time rather than instantly.

section {
  border: 1px solid black;
  padding: 20px;
  margin-top: 60px;
  height: 500px;
  overflow-y: scroll;
  scroll-behavior: smooth;
}

We also create two class selectors; when a fade-out or fade-in class is applied to an element, an animation is applied so that it smoothly fades out or in, respectively. We also define @keyframes blocks to define the required opacity changes for those animations.

.fade-out {
  animation: fade-out 0.3s linear both;
}

.fade-in {
  animation: fade-in 0.3s linear both;
}

@keyframes fade-out {
  from {
    opacity: 1;
  }

  to {
    opacity: 0;
  }
}

@keyframes fade-in {
  from {
    opacity: 0;
  }

  to {
    opacity: 1;
  }
}

The rest of the CSS is not shown, for brevity.

JavaScript

We start by grabbing references to the <button> that runs the scroll() operation, the toolbar <div>, and the scrolling <section>:

const scrollBtn = document.querySelector(".scroll");
const toolbar = document.querySelector("div");
const section = document.querySelector("section");

When the button is clicked, we immediately apply the fade-out class to the toolbar, causing it to fade out. We then run scroll(0, 1000) on the <section> to scroll its content down 1000 pixels, awaiting its promise resolution as we do so and storing the result in a constant. When the promise has resolved, we log a message to say that the scroll operation has finished and whether it was interrupted. Finally, we apply the fade-in class to the toolbar, causing it to fade back in again.

scrollBtn.addEventListener("click", async () => {
  toolbar.className = "fade-out";
  const result = await section.scroll(0, 1000);
  console.log(
    `Scroll finished;${result.interrupted ? " " : " not "}interrupted`,
  );
  toolbar.className = "fade-in";
});

The code not relevant to scroll() is not shown, for brevity.

Result

Load our element methods demo (see source code) in a new tab and click the buttons to see the scrolling behavior. Note how the toolbar fades out when a button is pressed, and fades in again once the smooth scrolling is finished.

Try pressing one button and then quickly pressing another button before the first scrolling operation has finished. Open your browser's JavaScript console and note how, in these cases, the scrolling is reported as interrupted.

Specifications

Browser compatibility