diff --git a/files/en-us/web/api/element/scroll/index.md b/files/en-us/web/api/element/scroll/index.md
index d9378e4fe1f9043..103058522041cd2 100644
--- a/files/en-us/web/api/element/scroll/index.md
+++ b/files/en-us/web/api/element/scroll/index.md
@@ -8,9 +8,7 @@ browser-compat: api.Element.scroll
 
 {{APIRef("CSSOM view API")}}
 
-The **`scroll()`** method of the {{domxref("Element")}}
-interface scrolls the element to a particular set of coordinates inside a given
-element.
+The **`scroll()`** method of the {{domxref("Element")}} interface scrolls to a particular set of coordinates inside a given element.
 
 ## Syntax
 
@@ -22,29 +20,34 @@ scroll(options)
 ### Parameters
 
 - `xCoord`
-  - : The pixel along the horizontal axis of the element that you want displayed in the
-    upper left.
+  - : 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.
+  - : 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`
+    - `top` {{optional_inline}}
       - : Specifies the number of pixels along the Y axis to scroll the window or element.
-    - `left`
+    - `left` {{optional_inline}}
       - : Specifies the number of pixels along the X axis to scroll the window or element.
-    - `behavior`
-      - : Determines whether scrolling is instant or animates smoothly. This option is a string which must take one of the following values:
-        - `smooth`: scrolling should animate smoothly
-        - `instant`: scrolling should happen instantly in a single jump
-        - `auto`: scroll behavior is determined by the computed value of {{cssxref("scroll-behavior")}}
+    - `behavior` {{optional_inline}}
+      - : 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 {{cssxref("scroll-behavior")}} CSS property on the element.
+
+        If omitted, `behavior` defaults to `auto`.
 
 ### Return value
 
-None ({{jsxref("undefined")}}).
+A {{jsxref("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
+
 ```js
 // Put the 1000th vertical pixel at the top of the element
 element.scroll(0, 1000);
@@ -60,6 +63,129 @@ element.scroll({
 });
 ```
 
+### Responding to the end of the scroll
+
+Our [element methods demo](https://mdn.github.io/dom-examples/scroll-promises/element-methods/) ([see source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/element-methods)) 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`](#behavior) option to `smooth`, or by setting the scrolling element's {{cssxref("scroll-behavior")}} property to `smooth`).
+
+#### HTML
+
+Our HTML includes a {{htmlelement("section")}} element containing several paragraphs of content and a {{htmlelement("div")}} element toolbar containing {{htmlelement("button")}} elements that trigger various scrolling operations on the `<section>`.
+
+```html
+<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 {{cssxref("height")}} and an {{cssxref("overflow-y")}} value of `scroll` so that it scrolls vertically, and set its {{cssxref("scroll-behavior")}} property to `smooth` so that any scroll operations are animated smoothly over time rather than instantly.
+
+```css
+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 {{cssxref("animation")}} is applied so that it smoothly fades out or in, respectively. We also define {{cssxref("@keyframes")}} blocks to define the required {{cssxref("opacity")}} changes for those animations.
+
+```css
+.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>`:
+
+```js
+const scrollBtn = document.querySelector(".scroll");
+const toolbar = document.querySelector("div");
+const section = document.querySelector("section");
+```
+
+Next, we define a function called `isInterrupted()`, designed to run in response to a scroll operation finishing, which takes a boolean `interrupted` value as a parameter. It logs a message to the console to say that scrolling is finished and indicate whether the operation was interrupted (`interrupted` is `true`) or not. In addition, if `interrupted` is `true`, it calls an `alert()` to clearly indicate the interruption.
+
+```js
+function isInterrupted(interrupted) {
+  console.log(`Scroll finished;${interrupted ? " " : " not "}interrupted`);
+  if (interrupted) {
+    alert("Scroll interrupted!");
+  }
+}
+```
+
+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, `await`ing its promise resolution as we do so and storing the `result` in a constant. When the promise has resolved, we call `isInterrupted()` to report 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.
+
+```js
+scrollBtn.addEventListener("click", async () => {
+  toolbar.className = "fade-out";
+  const result = await section.scroll(0, 1000);
+  isInterrupted(result.interrupted);
+  toolbar.className = "fade-in";
+});
+```
+
+The code not relevant to `scroll()` is not shown, for brevity.
+
+#### Result
+
+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. Also try pressing one button and then quickly pressing another button before the first scrolling operation has finished. Note how, in these cases, the scrolling is reported as interrupted.
+
+{{EmbedGHLiveSample("dom-examples/scroll-promises/element-methods/", "100%", 620)}}
+
+You can also [load the demo in a separate tab](https://mdn.github.io/dom-examples/scroll-promises/element-methods/) and view the [source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/element-methods).
+
+#### Aside on feature detection
+
+If you run this example in a browser that doesn't support promise-returning scroll operations, the scroll operations are still smooth, but the toolbar doesn't fade out and then fade back in once the operation is finished. The feature detection is handled by a function called `supportsScrollPromises()`, which runs a scroll operation and tests whether its return value is a promise:
+
+```js
+function supportsScrollPromises() {
+  const test = section.scroll(0, 0);
+  return test instanceof Promise;
+}
+```
+
+Check out the [source code](https://github.com/mdn/dom-examples/blob/main/scroll-promises/element-methods/index.js) to see how the feature detection is used.
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/api/element/scrollby/index.md b/files/en-us/web/api/element/scrollby/index.md
index a27cee42f45376d..5f63823eecef814 100644
--- a/files/en-us/web/api/element/scrollby/index.md
+++ b/files/en-us/web/api/element/scrollby/index.md
@@ -8,8 +8,7 @@ browser-compat: api.Element.scrollBy
 
 {{APIRef("CSSOM view API")}}
 
-The **`scrollBy()`** method of the {{domxref("Element")}}
-interface scrolls an element by the given amount.
+The **`scrollBy()`** method of the {{domxref("Element")}} interface scrolls an element by the given amount.
 
 ## Syntax
 
@@ -21,29 +20,34 @@ scrollBy(options)
 ### Parameters
 
 - `xCoord`
-  - : The horizontal pixel value that you want to
-    scroll by.
+  - : The horizontal pixel value that you want to scroll by.
 - `yCoord`
-  - : The vertical pixel value that you want to scroll
-    by.
+  - : The vertical pixel value that you want to scroll by.
 - `options`
   - : An object containing the following properties:
-    - `top`
+    - `top` {{optional_inline}}
       - : Specifies the number of pixels along the Y axis to scroll the window or element.
-    - `left`
+    - `left` {{optional_inline}}
       - : Specifies the number of pixels along the X axis to scroll the window or element.
-    - `behavior`
-      - : Determines whether the scrolling is instant or animates smoothly. This option is a string that must take one of the following values:
+    - `behavior` {{optional_inline}}
+      - : 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 {{cssxref("scroll-behavior")}} CSS property on the element.
 
+        If omitted, `behavior` defaults to `auto`.
+
 ### Return value
 
-None ({{jsxref("undefined")}}).
+A {{jsxref("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
+
 ```js
 // scroll an element
 element.scrollBy(300, 300);
@@ -59,6 +63,129 @@ element.scrollBy({
 });
 ```
 
+### Responding to the end of the scroll
+
+Our [element methods demo](https://mdn.github.io/dom-examples/scroll-promises/element-methods/) ([see source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/element-methods)) demonstrates how the promise return value of `scrollBy()` 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`](#behavior) option to `smooth`, or by setting the scrolling element's {{cssxref("scroll-behavior")}} property to `smooth`).
+
+#### HTML
+
+Our HTML includes a {{htmlelement("section")}} element containing several paragraphs of content and a {{htmlelement("div")}} element toolbar containing {{htmlelement("button")}} elements that trigger various scrolling operations on the `<section>`.
+
+```html
+<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 {{cssxref("height")}} and an {{cssxref("overflow-y")}} value of `scroll` so that it scrolls vertically, and set its {{cssxref("scroll-behavior")}} property to `smooth` so that any scroll operations are animated smoothly over time rather than instantly.
+
+```css
+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 {{cssxref("animation")}} is applied so that it smoothly fades out or in, respectively. We also define {{cssxref("@keyframes")}} blocks to define the required {{cssxref("opacity")}} changes for those animations.
+
+```css
+.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 `scrollBy()` operation, the toolbar `<div>`, and the scrolling `<section>`:
+
+```js
+const scrollByBtn = document.querySelector(".scrollby");
+const toolbar = document.querySelector("div");
+const section = document.querySelector("section");
+```
+
+Next, we define a function called `isInterrupted()`, designed to run in response to a scroll operation finishing, which takes a boolean `interrupted` value as a parameter. It logs a message to the console to say that scrolling is finished and indicate whether the operation was interrupted (`interrupted` is `true`) or not. In addition, if `interrupted` is `true`, it calls an `alert()` to clearly indicate the interruption.
+
+```js
+function isInterrupted(interrupted) {
+  console.log(`Scroll finished;${interrupted ? " " : " not "}interrupted`);
+  if (interrupted) {
+    alert("Scroll interrupted!");
+  }
+}
+```
+
+When the button is clicked, we immediately apply the `fade-out` class to the toolbar, causing it to fade out. We then run `scrollBy(0, 200)` on the `<section>` to scroll its content down by 200 pixels, `await`ing its promise resolution as we do so and storing the `result` in a constant. When the promise has resolved, we call `isInterrupted()` to report 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.
+
+```js
+scrollByBtn.addEventListener("click", async () => {
+  toolbar.className = "fade-out";
+  const result = await section.scrollBy(0, 200);
+  isInterrupted(result.interrupted);
+  toolbar.className = "fade-in";
+});
+```
+
+The code not relevant to `scrollBy()` is not shown, for brevity.
+
+#### Result
+
+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. Also try pressing one button and then quickly pressing another button before the first scrolling operation has finished. Note how, in these cases, the scrolling is reported as interrupted.
+
+{{EmbedGHLiveSample("dom-examples/scroll-promises/element-methods/", "100%", 620)}}
+
+You can also [load the demo in a separate tab](https://mdn.github.io/dom-examples/scroll-promises/element-methods/) and view the [source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/element-methods).
+
+#### Aside on feature detection
+
+If you run this example in a browser that doesn't support promise-returning scroll operations, the scroll operations are still smooth, but the toolbar doesn't fade out and then fade back in once the operation is finished. The feature detection is handled by a function called `supportsScrollPromises()`, which runs a scroll operation and tests whether its return value is a promise:
+
+```js
+function supportsScrollPromises() {
+  const test = section.scroll(0, 0);
+  return test instanceof Promise;
+}
+```
+
+Check out the [source code](https://github.com/mdn/dom-examples/blob/main/scroll-promises/element-methods/index.js) to see how the feature detection is used.
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/api/element/scrollintoview/index.md b/files/en-us/web/api/element/scrollintoview/index.md
index abf537837cce61e..e43999ca7a072d2 100644
--- a/files/en-us/web/api/element/scrollintoview/index.md
+++ b/files/en-us/web/api/element/scrollintoview/index.md
@@ -8,10 +8,7 @@ browser-compat: api.Element.scrollIntoView
 
 {{APIRef("DOM")}}
 
-The {{domxref("Element")}} interface's
-**`scrollIntoView()`** method scrolls the element's ancestor
-containers such that the element on which `scrollIntoView()` is called is
-visible to the user.
+The **`scrollIntoView()`** method of the {{domxref("Element")}} interface scrolls the element's ancestor containers such that the element on which `scrollIntoView()` is called is visible to the user.
 
 ## Syntax
 
@@ -31,17 +28,21 @@ scrollIntoView(options)
       the default value.
     - If `false`, the bottom of the element will be aligned to the bottom
       of the visible area of the scrollable ancestor. Corresponds to
-      `scrollIntoViewOptions: {block: "end", inline: "nearest"}`.
+- If `true`, the top of the element will be aligned to the top of the visible area of the scrollable ancestor.
+  Corresponds to `scrollIntoViewOptions: {block: "start", inline: "nearest"}`.
+  This is the default value.
+- If `false`, the bottom of the element will be aligned to the bottom of the visible area of the scrollable ancestor.
+  Corresponds to `scrollIntoViewOptions: {block: "end", inline: "nearest"}`.
 
 - `options` {{optional_inline}}
   - : An object with the following properties:
     - `behavior` {{optional_inline}}
-      - : Determines whether scrolling is instant or animates smoothly. Its value can be one of the following:
-        - `smooth`: scrolling should animate smoothly
-        - `instant`: scrolling should happen instantly in a single jump
-        - `auto`: scroll behavior is determined by the computed value of {{cssxref("scroll-behavior")}}
+      - : 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 {{cssxref("scroll-behavior")}} CSS property on the element.
 
-        The default is `auto`.
+        If omitted, `behavior` defaults to `auto`.
 
     - `block` {{optional_inline}}
       - : Defines the vertical alignment of the element within the scrollable ancestor container. Its value can be one of the following:
@@ -70,11 +71,14 @@ scrollIntoView(options)
 
 ### Return value
 
-None ({{jsxref("undefined")}}).
+A {{jsxref("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
 
-### Using scrollIntoView()
+### Basic usage
 
 ```js
 const element = document.getElementById("box");
@@ -91,7 +95,7 @@ By default, the element is aligned to the top (or bottom) edge of the scrollable
 
 #### HTML
 
-```html
+```html live-sample___scroll-with-padding
 <body>
   <header class="navbar">Navbar</header>
   <main class="content">
@@ -103,7 +107,7 @@ By default, the element is aligned to the top (or bottom) edge of the scrollable
 
 #### CSS
 
-```css
+```css live-sample___scroll-with-padding
 .navbar {
   height: 50px;
   position: sticky;
@@ -133,7 +137,7 @@ By default, the element is aligned to the top (or bottom) edge of the scrollable
 
 #### JavaScript
 
-```js
+```js live-sample___scroll-with-padding
 const goToTop = document.getElementById("go-to-top");
 const goToBottom = document.getElementById("go-to-bottom");
 goToBottom.addEventListener("click", () => {
@@ -148,6 +152,133 @@ goToTop.addEventListener("click", () => {
 
 {{EmbedLiveSample("scroll-with-padding", "700", "300")}}
 
+### Responding to the end of the scroll
+
+Our [element methods demo](https://mdn.github.io/dom-examples/scroll-promises/element-methods/) ([see source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/element-methods)) demonstrates how the promise return value of `scrollIntoView()` 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`](#behavior) option to `smooth`, or by setting the scrolling element's {{cssxref("scroll-behavior")}} property to `smooth`).
+
+#### HTML
+
+Our HTML includes a {{htmlelement("section")}} element containing several paragraphs of content and a {{htmlelement("div")}} element toolbar containing {{htmlelement("button")}} elements that trigger various scrolling operations on the `<section>`. The last paragraph has an `id` of `end`.
+
+```html
+<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>
+  ...
+
+  <p id="end">...</p>
+</section>
+```
+
+#### CSS
+
+We give the `<section>` element a fixed {{cssxref("height")}} and an {{cssxref("overflow-y")}} value of `scroll` so that it scrolls vertically, and set its {{cssxref("scroll-behavior")}} property to `smooth` so that any scroll operations are animated smoothly over time rather than instantly.
+
+```css
+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 {{cssxref("animation")}} is applied so that it smoothly fades out or in, respectively. We also define {{cssxref("@keyframes")}} blocks to define the required {{cssxref("opacity")}} changes for those animations.
+
+```css
+.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 `scrollIntoView()` operation, the toolbar `<div>`, and the paragraph with an `id` of `end`:
+
+```js
+const scrollIntoViewBtn = document.querySelector(".scrollintoview");
+const toolbar = document.querySelector("div");
+const end = document.querySelector("#end");
+```
+
+Next, we define a function called `isInterrupted()`, designed to run in response to a scroll operation finishing, which takes a boolean `interrupted` value as a parameter. It logs a message to the console to say that scrolling is finished and indicate whether the operation was interrupted (`interrupted` is `true`) or not. In addition, if `interrupted` is `true`, it calls an `alert()` to clearly indicate the interruption.
+
+```js
+function isInterrupted(interrupted) {
+  console.log(`Scroll finished;${interrupted ? " " : " not "}interrupted`);
+  if (interrupted) {
+    alert("Scroll interrupted!");
+  }
+}
+```
+
+When the button is clicked, we immediately apply the `fade-out` class to the toolbar, causing it to fade out. We then run `scrollIntoView()` on the end paragraph to cause the `<section>` to scroll until the end paragraph is in view, `await`ing its promise resolution as we do so and storing the `result` in a constant. When the promise has resolved, we call `isInterrupted()` to report 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.
+
+```js
+scrollIntoViewBtn.addEventListener("click", async () => {
+  toolbar.className = "fade-out";
+  const result = await end.scrollIntoView();
+  isInterrupted(result.interrupted);
+  toolbar.className = "fade-in";
+});
+```
+
+The code not relevant to `scrollIntoView()` is not shown, for brevity.
+
+#### Result
+
+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. Also try pressing one button and then quickly pressing another button before the first scrolling operation has finished. Note how, in these cases, the scrolling is reported as interrupted.
+
+{{EmbedGHLiveSample("dom-examples/scroll-promises/element-methods/", "100%", 620)}}
+
+You can also [load the demo in a separate tab](https://mdn.github.io/dom-examples/scroll-promises/element-methods/) and view the [source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/element-methods).
+
+#### Aside on feature detection
+
+If you run this example in a browser that doesn't support promise-returning scroll operations, the scroll operations are still smooth, but the toolbar doesn't fade out and then fade back in once the operation is finished. The feature detection is handled by a function called `supportsScrollPromises()`, which runs a scroll operation and tests whether its return value is a promise:
+
+```js
+function supportsScrollPromises() {
+  const test = section.scroll(0, 0);
+  return test instanceof Promise;
+}
+```
+
+Check out the [source code](https://github.com/mdn/dom-examples/blob/main/scroll-promises/element-methods/index.js) to see how the feature detection is used.
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/api/element/scrollto/index.md b/files/en-us/web/api/element/scrollto/index.md
index 8ac27d5785f46e8..e37c4ce83611bbe 100644
--- a/files/en-us/web/api/element/scrollto/index.md
+++ b/files/en-us/web/api/element/scrollto/index.md
@@ -8,8 +8,7 @@ browser-compat: api.Element.scrollTo
 
 {{APIRef("CSSOM view API")}}
 
-The **`scrollTo()`** method of the {{domxref("Element")}}
-interface scrolls to a particular set of coordinates inside a given element.
+The **`scrollTo()`** method of the {{domxref("Element")}} interface scrolls to a particular set of coordinates inside a given element.
 
 This method is an alias for {{domxref("Element.scroll()")}}.
 
@@ -28,22 +27,29 @@ scrollTo(options)
   - : The y-coordinate of the element's scrollable content that you want the top edge of the element's scrollport to scroll to.
 - `options`
   - : An object containing the following properties:
-    - `top`
+    - `top` {{optional_inline}}
       - : The y-coordinate of the element's scrollable content that you want the top edge of the element's scrollport to scroll to. This is the same as the `yCoord` parameter.
-    - `left`
+    - `left` {{optional_inline}}
       - : The x-coordinate of the element's scrollable content that you want the left edge of the element's scrollport to scroll to. This is the same as the `xCoord` parameter.
-    - `behavior`
-      - : Determines whether the scrolling is instant or animates smoothly. This option is a string that must take one of the following values:
+    - `behavior` {{optional_inline}}
+      - : 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 {{cssxref("scroll-behavior")}} CSS property on the element.
 
+        If omitted, `behavior` defaults to `auto`.
+
 ### Return value
 
-None ({{jsxref("undefined")}}).
+A {{jsxref("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
+
 ```js
 element.scrollTo(0, 1000);
 ```
@@ -58,6 +64,129 @@ element.scrollTo({
 });
 ```
 
+### Responding to the end of the scroll
+
+Our [element methods demo](https://mdn.github.io/dom-examples/scroll-promises/element-methods/) ([see source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/element-methods)) demonstrates how the promise return value of `scrollTo()` 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`](#behavior) option to `smooth`, or by setting the scrolling element's {{cssxref("scroll-behavior")}} property to `smooth`).
+
+#### HTML
+
+Our HTML includes a {{htmlelement("section")}} element containing several paragraphs of content and a {{htmlelement("div")}} element toolbar containing {{htmlelement("button")}} elements that trigger various scrolling operations on the `<section>`.
+
+```html
+<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 {{cssxref("height")}} and an {{cssxref("overflow-y")}} value of `scroll` so that it scrolls vertically, and set its {{cssxref("scroll-behavior")}} property to `smooth` so that any scroll operations are animated smoothly over time rather than instantly.
+
+```css
+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 {{cssxref("animation")}} is applied so that it smoothly fades out or in, respectively. We also define {{cssxref("@keyframes")}} blocks to define the required {{cssxref("opacity")}} changes for those animations.
+
+```css
+.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 `scrollTo()` operation, the toolbar `<div>`, and the scrolling `<section>`:
+
+```js
+const scrollToBtn = document.querySelector(".scrollto");
+const toolbar = document.querySelector("div");
+const section = document.querySelector("section");
+```
+
+Next, we define a function called `isInterrupted()`, designed to run in response to a scroll operation finishing, which takes a boolean `interrupted` value as a parameter. It logs a message to the console to say that scrolling is finished and indicate whether the operation was interrupted (`interrupted` is `true`) or not. In addition, if `interrupted` is `true`, it calls an `alert()` to clearly indicate the interruption.
+
+```js
+function isInterrupted(interrupted) {
+  console.log(`Scroll finished;${interrupted ? " " : " not "}interrupted`);
+  if (interrupted) {
+    alert("Scroll interrupted!");
+  }
+}
+```
+
+When the button is clicked, we immediately apply the `fade-out` class to the toolbar, causing it to fade out. We then run `scrollTo(0, 0)` on the `<section>` to scroll its content to the top, `await`ing its promise resolution as we do so and storing the `result` in a constant. When the promise has resolved, we call `isInterrupted()` to report 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.
+
+```js
+scrollToBtn.addEventListener("click", async () => {
+  toolbar.className = "fade-out";
+  const result = await section.scrollTo(0, 0);
+  isInterrupted(result.interrupted);
+  toolbar.className = "fade-in";
+});
+```
+
+The code not relevant to `scrollTo()` is not shown, for brevity.
+
+#### Result
+
+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. Also try pressing one button and then quickly pressing another button before the first scrolling operation has finished. Note how, in these cases, the scrolling is reported as interrupted.
+
+{{EmbedGHLiveSample("dom-examples/scroll-promises/element-methods/", "100%", 620)}}
+
+You can also [load the demo in a separate tab](https://mdn.github.io/dom-examples/scroll-promises/element-methods/) and view the [source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/element-methods).
+
+#### Aside on feature detection
+
+If you run this example in a browser that doesn't support promise-returning scroll operations, the scroll operations are still smooth, but the toolbar doesn't fade out and then fade back in once the operation is finished. The feature detection is handled by a function called `supportsScrollPromises()`, which runs a scroll operation and tests whether its return value is a promise:
+
+```js
+function supportsScrollPromises() {
+  const test = section.scroll(0, 0);
+  return test instanceof Promise;
+}
+```
+
+Check out the [source code](https://github.com/mdn/dom-examples/blob/main/scroll-promises/element-methods/index.js) to see how the feature detection is used.
+
 ## Specifications
 
 {{Specifications}}
diff --git a/files/en-us/web/api/window/scroll/index.md b/files/en-us/web/api/window/scroll/index.md
index 5e9ee67f8c682c4..3de31be4045d5e2 100644
--- a/files/en-us/web/api/window/scroll/index.md
+++ b/files/en-us/web/api/window/scroll/index.md
@@ -8,8 +8,7 @@ browser-compat: api.Window.scroll
 
 {{APIRef}}
 
-The **`Window.scroll()`** method scrolls the window to a
-particular place in the document.
+The **`scroll()`** method of the {{domxref("Window")}} interface scrolls the window to a particular place in the document.
 
 ## Syntax
 
@@ -21,29 +20,34 @@ scroll(options)
 ### Parameters
 
 - `xCoord`
-  - : The pixel along the horizontal axis of the document that you
-    want displayed in the upper left.
+  - : The pixel along the horizontal axis of the document that you want displayed in the upper left.
 - `yCoord`
-  - : The pixel along the vertical axis of the document that you
-    want displayed in the upper left.
+  - : The pixel along the vertical axis of the document that you want displayed in the upper left.
 - `options`
   - : An object containing the following properties:
-    - `top`
+    - `top` {{optional_inline}}
       - : Specifies the number of pixels along the Y axis to scroll the window or element.
-    - `left`
+    - `left` {{optional_inline}}
       - : Specifies the number of pixels along the X axis to scroll the window or element.
-    - `behavior`
-      - : Determines whether scrolling is instant or animates smoothly. This option is a string which must take one of the following values:
-        - `smooth`: scrolling should animate smoothly
-        - `instant`: scrolling should happen instantly in a single jump
-        - `auto`: scroll behavior is determined by the computed value of {{cssxref("scroll-behavior")}}
+    - `behavior` {{optional_inline}}
+      - : 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 {{cssxref("scroll-behavior")}} CSS property on the element.
+
+        If omitted, `behavior` defaults to `auto`.
 
 ### Return value
 
-None ({{jsxref("undefined")}}).
+A {{jsxref("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 window before the first one finishes.
 
 ## Examples
 
+### Basic usage
+
 ```js
 // Put the 100th vertical pixel at the top of the window
 window.scroll(0, 100);
@@ -59,14 +63,125 @@ window.scroll({
 });
 ```
 
-## Notes
+### Responding to the end of the scroll
+
+Our [window methods demo](https://mdn.github.io/dom-examples/scroll-promises/window-methods/) ([see source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/window-methods)) 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`](#behavior) option to `smooth`, or by setting the scrolling element's {{cssxref("scroll-behavior")}} property to `smooth`).
+
+#### HTML
+
+Our HTML includes several paragraphs of content and a {{htmlelement("div")}} element toolbar containing {{htmlelement("button")}} elements that trigger various scrolling operations on the window.
+
+```html
+<div>
+  <button class="scroll">scroll() to 1000</button>
+  <button class="scrollto">scrollTo() top</button>
+  <button class="scrollby">scrollBy() 200</button>
+</div>
+
+<p>...</p>
+
+<p>...</p>
+
+...
+```
+
+#### CSS
+
+We give the {{cssxref(":root")}} element a {{cssxref("scroll-behavior")}} property value of `smooth` so that any scroll operations are animated smoothly over time rather than instantly.
+
+```css
+:root {
+  scroll-behavior: smooth;
+}
+```
+
+We also create two class selectors; when a `fade-out` or `fade-in` class is applied to an element, an {{cssxref("animation")}} is applied so that it smoothly fades out or in, respectively. We also define {{cssxref("@keyframes")}} blocks to define the required {{cssxref("opacity")}} changes for those animations.
+
+```css
+.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.
 
-{{domxref("Window.scrollTo()")}} is effectively the same as this method. For relative
-scrolling, see {{domxref("Window.scrollBy()")}}, {{domxref("Window.scrollByLines()")}},
-and {{domxref("Window.scrollByPages()")}}.
+#### JavaScript
+
+We start by grabbing references to the `<button>` that runs the `scroll()` operation and the toolbar `<div>`:
+
+```js
+const scrollBtn = document.querySelector(".scroll");
+const toolbar = document.querySelector("div");
+```
+
+Next, we define a function called `isInterrupted()`, designed to run in response to a scroll operation finishing, which takes a boolean `interrupted` value as a parameter. It logs a message to the console to say that scrolling is finished and indicate whether the operation was interrupted (`interrupted` is `true`) or not. In addition, if `interrupted` is `true`, it calls an `alert()` to clearly indicate the interruption.
+
+```js
+function isInterrupted(interrupted) {
+  console.log(`Scroll finished;${interrupted ? " " : " not "}interrupted`);
+  if (interrupted) {
+    alert("Scroll interrupted!");
+  }
+}
+```
+
+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 window to scroll its content down 1000 pixels, `await`ing its promise resolution as we do so and storing the `result` in a constant. When the promise has resolved, we call `isInterrupted()` to report 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.
+
+```js
+scrollBtn.addEventListener("click", async () => {
+  toolbar.className = "fade-out";
+  const result = await window.scroll(0, 1000);
+  isInterrupted(result.interrupted);
+  toolbar.className = "fade-in";
+});
+```
+
+The code not relevant to `scroll()` is not shown, for brevity.
+
+#### Result
+
+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. Also try pressing one button and then quickly pressing another button before the first scrolling operation has finished. Note how, in these cases, the scrolling is reported as interrupted.
+
+{{EmbedGHLiveSample("dom-examples/scroll-promises/window-methods/", "100%", 400)}}
+
+You can also [load the demo in a separate tab](https://mdn.github.io/dom-examples/scroll-promises/window-methods/) and view the [source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/window-methods).
+
+#### Aside on feature detection
+
+If you run this example in a browser that doesn't support promise-returning scroll operations, the scroll operations are still smooth, but the toolbar doesn't fade out and then fade back in once the operation is finished. The feature detection is handled by a function called `supportsScrollPromises()`, which runs a scroll operation and tests whether its return value is a promise:
+
+```js
+function supportsScrollPromises() {
+  const test = window.scroll(0, 0);
+  return test instanceof Promise;
+}
+```
 
-For scrolling elements, see {{domxref("Element.scrollTop")}} and
-{{domxref("Element.scrollLeft")}}.
+Check out the [source code](https://github.com/mdn/dom-examples/blob/main/scroll-promises/window-methods/index.js) to see how the feature detection is used.
 
 ## Specifications
 
@@ -78,6 +193,8 @@ For scrolling elements, see {{domxref("Element.scrollTop")}} and
 
 ## See also
 
-- {{domxref("Window.scrollByLines()")}}
-- {{domxref("Window.scrollByPages()")}}
-- {{domxref("Element.scrollIntoView()")}}
+- {{domxref("Window.scrollTo()")}}
+- {{domxref("Window.scrollBy()")}}
+- {{domxref("Element.scroll()")}}
+- {{domxref("Window.scrollByLines()")}} {{non-standard_inline}}
+- {{domxref("Window.scrollByPages()")}} {{non-standard_inline}}
diff --git a/files/en-us/web/api/window/scrollby/index.md b/files/en-us/web/api/window/scrollby/index.md
index 7ae1049bf97862c..ed900ce8702b203 100644
--- a/files/en-us/web/api/window/scrollby/index.md
+++ b/files/en-us/web/api/window/scrollby/index.md
@@ -8,8 +8,7 @@ browser-compat: api.Window.scrollBy
 
 {{APIRef}}
 
-The **`Window.scrollBy()`** method scrolls the document in the
-window by the given amount.
+The **`scrollBy()`** method of the {{domxref("Window")}} interface scrolls the document in the window by the given amount.
 
 ## Syntax
 
@@ -26,22 +25,29 @@ scrollBy(options)
   - : The vertical pixel value that you want to scroll by.
 - `options`
   - : An object containing the following properties:
-    - `top`
+    - `top` {{optional_inline}}
       - : Specifies the number of pixels along the Y axis to scroll the window or element.
-    - `left`
+    - `left` {{optional_inline}}
       - : Specifies the number of pixels along the X axis to scroll the window or element.
-    - `behavior`
-      - : Determines whether the scrolling is instant or animates smoothly. This option is a string that must take one of the following values:
+    - `behavior` {{optional_inline}}
+      - : 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 {{cssxref("scroll-behavior")}} CSS property on the document.
+        - `auto`: The scroll behavior is determined by the computed value of the {{cssxref("scroll-behavior")}} CSS property on the element.
+
+        If omitted, `behavior` defaults to `auto`.
 
 ### Return value
 
-None ({{jsxref("undefined")}}).
+A {{jsxref("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 window before the first one finishes.
 
 ## Examples
 
+### Basic usage
+
 To scroll down one page:
 
 ```js
@@ -64,11 +70,125 @@ window.scrollBy({
 });
 ```
 
-## Notes
+### Responding to the end of the scroll
+
+Our [window methods demo](https://mdn.github.io/dom-examples/scroll-promises/window-methods/) ([see source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/window-methods)) demonstrates how the promise return value of `scrollBy()` 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`](#behavior) option to `smooth`, or by setting the scrolling element's {{cssxref("scroll-behavior")}} property to `smooth`).
+
+#### HTML
+
+Our HTML includes several paragraphs of content and a {{htmlelement("div")}} element toolbar containing {{htmlelement("button")}} elements that trigger various scrolling operations on the window.
+
+```html
+<div>
+  <button class="scroll">scroll() to 1000</button>
+  <button class="scrollto">scrollTo() top</button>
+  <button class="scrollby">scrollBy() 200</button>
+</div>
+
+<p>...</p>
+
+<p>...</p>
+
+...
+```
+
+#### CSS
+
+We give the {{cssxref(":root")}} element a {{cssxref("scroll-behavior")}} property value of `smooth` so that any scroll operations are animated smoothly over time rather than instantly.
+
+```css
+:root {
+  scroll-behavior: smooth;
+}
+```
+
+We also create two class selectors; when a `fade-out` or `fade-in` class is applied to an element, an {{cssxref("animation")}} is applied so that it smoothly fades out or in, respectively. We also define {{cssxref("@keyframes")}} blocks to define the required {{cssxref("opacity")}} changes for those animations.
+
+```css
+.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 `scrollBy()` operation and the toolbar `<div>`:
+
+```js
+const scrollByBtn = document.querySelector(".scrollby");
+const toolbar = document.querySelector("div");
+```
+
+Next, we define a function called `isInterrupted()`, designed to run in response to a scroll operation finishing, which takes a boolean `interrupted` value as a parameter. It logs a message to the console to say that scrolling is finished and indicate whether the operation was interrupted (`interrupted` is `true`) or not. In addition, if `interrupted` is `true`, it calls an `alert()` to clearly indicate the interruption.
+
+```js
+function isInterrupted(interrupted) {
+  console.log(`Scroll finished;${interrupted ? " " : " not "}interrupted`);
+  if (interrupted) {
+    alert("Scroll interrupted!");
+  }
+}
+```
+
+When the button is clicked, we immediately apply the `fade-out` class to the toolbar, causing it to fade out. We then run `scrollBy(0, 200)` on the window to scroll its content down by 200 pixels, `await`ing its promise resolution as we do so and storing the `result` in a constant. When the promise has resolved, we call `isInterrupted()` to report 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.
+
+```js
+scrollByBtn.addEventListener("click", async () => {
+  toolbar.className = "fade-out";
+  const result = await window.scrollBy(0, 200);
+  isInterrupted(result.interrupted);
+  toolbar.className = "fade-in";
+});
+```
+
+The code not relevant to `scrollBy()` is not shown, for brevity.
+
+#### Result
+
+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. Also try pressing one button and then quickly pressing another button before the first scrolling operation has finished. Note how, in these cases, the scrolling is reported as interrupted.
+
+{{EmbedGHLiveSample("dom-examples/scroll-promises/window-methods/", "100%", 400)}}
+
+You can also [load the demo in a separate tab](https://mdn.github.io/dom-examples/scroll-promises/window-methods/) and view the [source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/window-methods).
+
+#### Aside on feature detection
 
-`window.scrollBy()` scrolls by a particular amount, whereas
-{{domxref("window.scroll()")}} scrolls to an absolute position in the document. See also
-{{domxref("window.scrollByLines()")}} and {{domxref("window.scrollByPages()")}}.
+If you run this example in a browser that doesn't support promise-returning scroll operations, the scroll operations are still smooth, but the toolbar doesn't fade out and then fade back in once the operation is finished. The feature detection is handled by a function called `supportsScrollPromises()`, which runs a scroll operation and tests whether its return value is a promise:
+
+```js
+function supportsScrollPromises() {
+  const test = window.scroll(0, 0);
+  return test instanceof Promise;
+}
+```
+
+Check out the [source code](https://github.com/mdn/dom-examples/blob/main/scroll-promises/window-methods/index.js) to see how the feature detection is used.
 
 ## Specifications
 
@@ -77,3 +197,11 @@ window.scrollBy({
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{domxref("Window.scroll()")}}
+- {{domxref("Window.scrollTo()")}}
+- {{domxref("Element.scrollBy()")}}
+- {{domxref("Window.scrollByLines()")}} {{non-standard_inline}}
+- {{domxref("Window.scrollByPages()")}} {{non-standard_inline}}
diff --git a/files/en-us/web/api/window/scrollto/index.md b/files/en-us/web/api/window/scrollto/index.md
index 4b4b6bb6027c5f0..8791054888f0885 100644
--- a/files/en-us/web/api/window/scrollto/index.md
+++ b/files/en-us/web/api/window/scrollto/index.md
@@ -8,8 +8,7 @@ browser-compat: api.Window.scrollTo
 
 {{APIRef}}
 
-**`Window.scrollTo()`** scrolls to a particular set of
-coordinates in the document.
+The **`scrollTo()`** method of the {{domxref("Window")}} interface scrolls to a particular set of coordinates in the document.
 
 ## Syntax
 
@@ -26,22 +25,29 @@ scrollTo(options)
   - : The y-coordinate of the document that you want the viewport's top edge to scroll to.
 - `options`
   - : An object containing the following properties:
-    - `top`
+    - `top` {{optional_inline}}
       - : The y-coordinate of the document that you want the viewport's top edge to scroll to. This is the same as the `yCoord` parameter.
-    - `left`
+    - `left` {{optional_inline}}
       - : The x-coordinate of the document that you want the viewport's left edge to scroll to. This is the same as the `xCoord` parameter.
-    - `behavior`
-      - : Determines whether the scrolling is instant or animates smoothly. This option is a string that must take one of the following values:
+    - `behavior` {{optional_inline}}
+      - : 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 {{cssxref("scroll-behavior")}} CSS property on the document.
+        - `auto`: The scroll behavior is determined by the computed value of the {{cssxref("scroll-behavior")}} CSS property on the element.
+
+        If omitted, `behavior` defaults to `auto`.
 
 ### Return value
 
-None ({{jsxref("undefined")}}).
+A {{jsxref("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 window before the first one finishes.
 
 ## Examples
 
+### Basic usage
+
 ```js
 window.scrollTo(0, 1000);
 ```
@@ -56,14 +62,125 @@ window.scrollTo({
 });
 ```
 
-## Notes
+### Responding to the end of the scroll
+
+Our [window methods demo](https://mdn.github.io/dom-examples/scroll-promises/window-methods/) ([see source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/window-methods)) demonstrates how the promise return value of `scrollTo()` 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`](#behavior) option to `smooth`, or by setting the scrolling element's {{cssxref("scroll-behavior")}} property to `smooth`).
+
+#### HTML
+
+Our HTML includes several paragraphs of content and a {{htmlelement("div")}} element toolbar containing {{htmlelement("button")}} elements that trigger various scrolling operations on the window.
+
+```html
+<div>
+  <button class="scroll">scroll() to 1000</button>
+  <button class="scrollto">scrollTo() top</button>
+  <button class="scrollby">scrollBy() 200</button>
+</div>
 
-{{domxref("Window.scroll()")}} is effectively the same as this method. For relative
-scrolling, see {{domxref("Window.scrollBy()")}}, {{domxref("Window.scrollByLines()")}},
-and {{domxref("Window.scrollByPages()")}}.
+<p>...</p>
 
-For scrolling elements, see {{domxref("Element.scrollTop")}} and
-{{domxref("Element.scrollLeft")}}.
+<p>...</p>
+
+...
+```
+
+#### CSS
+
+We give the {{cssxref(":root")}} element a {{cssxref("scroll-behavior")}} property value of `smooth` so that any scroll operations are animated smoothly over time rather than instantly.
+
+```css
+:root {
+  scroll-behavior: smooth;
+}
+```
+
+We also create two class selectors; when a `fade-out` or `fade-in` class is applied to an element, an {{cssxref("animation")}} is applied so that it smoothly fades out or in, respectively. We also define {{cssxref("@keyframes")}} blocks to define the required {{cssxref("opacity")}} changes for those animations.
+
+```css
+.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 `scrollTo()` operation and the toolbar `<div>`:
+
+```js
+const scrollToBtn = document.querySelector(".scrollto");
+const toolbar = document.querySelector("div");
+```
+
+Next, we define a function called `isInterrupted()`, designed to run in response to a scroll operation finishing, which takes a boolean `interrupted` value as a parameter. It logs a message to the console to say that scrolling is finished and indicate whether the operation was interrupted (`interrupted` is `true`) or not. In addition, if `interrupted` is `true`, it calls an `alert()` to clearly indicate the interruption.
+
+```js
+function isInterrupted(interrupted) {
+  console.log(`Scroll finished;${interrupted ? " " : " not "}interrupted`);
+  if (interrupted) {
+    alert("Scroll interrupted!");
+  }
+}
+```
+
+When the button is clicked, we immediately apply the `fade-out` class to the toolbar, causing it to fade out. We then run `scrollTo(0, 0)` on the window to scroll its content up to the top, `await`ing its promise resolution as we do so and storing the `result` in a constant. When the promise has resolved, we call `isInterrupted()` to report 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.
+
+```js
+scrollToBtn.addEventListener("click", async () => {
+  toolbar.className = "fade-out";
+  const result = await window.scrollTo(0, 0);
+  isInterrupted(result.interrupted);
+  toolbar.className = "fade-in";
+});
+```
+
+The code not relevant to `scrollTo()` is not shown, for brevity.
+
+#### Result
+
+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. Also try pressing one button and then quickly pressing another button before the first scrolling operation has finished. Note how, in these cases, the scrolling is reported as interrupted.
+
+{{EmbedGHLiveSample("dom-examples/scroll-promises/window-methods/", "100%", 400)}}
+
+You can also [load the demo in a separate tab](https://mdn.github.io/dom-examples/scroll-promises/window-methods/) and view the [source code](https://github.com/mdn/dom-examples/tree/main/scroll-promises/window-methods).
+
+#### Aside on feature detection
+
+If you run this example in a browser that doesn't support promise-returning scroll operations, the scroll operations are still smooth, but the toolbar doesn't fade out and then fade back in once the operation is finished. The feature detection is handled by a function called `supportsScrollPromises()`, which runs a scroll operation and tests whether its return value is a promise:
+
+```js
+function supportsScrollPromises() {
+  const test = window.scroll(0, 0);
+  return test instanceof Promise;
+}
+```
+
+Check out the [source code](https://github.com/mdn/dom-examples/blob/main/scroll-promises/window-methods/index.js) to see how the feature detection is used.
 
 ## Specifications
 
@@ -72,3 +189,11 @@ For scrolling elements, see {{domxref("Element.scrollTop")}} and
 ## Browser compatibility
 
 {{Compat}}
+
+## See also
+
+- {{domxref("Window.scroll()")}}
+- {{domxref("Window.scrollBy()")}}
+- {{domxref("Element.scrollTo()")}}
+- {{domxref("Window.scrollByLines()")}} {{non-standard_inline}}
+- {{domxref("Window.scrollByPages()")}} {{non-standard_inline}}