Clarify values for scroll{Top,Left,X,Y} (mdn#34105)

FormularSumo · Jun 13, 2024 · d80aa2a · d80aa2a
1 parent d9c217c
commit d80aa2a
Show file tree

Hide file tree

Showing 4 changed files with 27 additions and 74 deletions.
diff --git a/files/en-us/web/api/element/scrollleft/index.md b/files/en-us/web/api/element/scrollleft/index.md
@@ -8,29 +8,17 @@ browser-compat: api.Element.scrollLeft
 
 {{APIRef("DOM")}}
 
-The **`Element.scrollLeft`** property gets or sets the number
-of pixels that an element's content is scrolled from its left edge.
+The **`Element.scrollLeft`** property gets or sets the number of pixels by which an element's content is scrolled from its left edge. This value is subpixel precise in modern browsers, meaning that it isn't necessarily a whole number.
 
-If the element's {{cssxref("direction")}} is `rtl` (right-to-left), then
-`scrollLeft` is `0` when the scrollbar is at its rightmost
-position (at the start of the scrolled content), and then increasingly negative as you
-scroll towards the end of the content.
-
-It can be specified as any integer value. However:
+## Value
 
-- If the element can't be scrolled (e.g., it has no overflow), `scrollLeft`
-  is set to `0`.
-- If specified as a value less than `0` (greater than `0` for
-  right-to-left elements), `scrollLeft` is set to `0`.
-- If specified as a value greater than the maximum that the content can be scrolled,
-  `scrollLeft` is set to the maximum.
+A double-precision floating-point value indicating the number of pixels by which the element is currently scrolled horizontally from the origin, where a positive value means the element is scrolled to the right (to reveal more content to the right). If the element isn't scrolled at all left or right, then `scrollLeft` is 0. If the document is not the active document, the returned value is 0. If the document is rendered on a subpixel-precise device, then the returned value is also subpixel-precise and may contain a decimal component.
 
-> **Warning:** On systems using display scaling, `scrollLeft` may give you a decimal
-> value.
+It's possible for `scrollLeft` to be negative if the element can be scrolled to the left from the initial containing block. For example, if the element's {{cssxref("direction")}} is `rtl` (right-to-left) and content grows to the left, then `scrollLeft` is `0` when the scrollbar is at its rightmost position (at the start of the scrolled content), and then increasingly negative as you scroll towards the end of the content.
 
-## Value
+Safari responds to overscrolling by updating `scrollLeft` beyond the maximum scroll position (unless the default "bounce" effect is disabled, such as by setting {{cssxref("overscroll-behavior")}} to `none`), while Chrome and Firefox do not.
 
-A number.
+The `scrollLeft` property can be set, which causes the element to scroll to the specified horizontal position, in the same way as using {{domxref("Element.scroll()")}} with `behavior: "auto"`.
 
 ## Examples
 

diff --git a/files/en-us/web/api/element/scrolltop/index.md b/files/en-us/web/api/element/scrolltop/index.md
@@ -8,23 +8,17 @@ browser-compat: api.Element.scrollTop
 
 {{APIRef("DOM")}}
 
-The **`Element.scrollTop`** property gets or sets the number of pixels that an element's content is scrolled vertically.
+The **`Element.scrollTop`** property gets or sets the number of pixels by which an element's content is scrolled from its top edge. This value is subpixel precise in modern browsers, meaning that it isn't necessarily a whole number.
 
-An element's `scrollTop` value is a measurement of the distance from the element's top to its topmost _visible_ content. When an element's content does not generate a vertical scrollbar, then its `scrollTop` value is `0`.
-
-`scrollTop` can be set to any integer value, with certain caveats:
-
-- If the element can't be scrolled (e.g. it has no overflow or if the element has a property of "**non-scrollable**"), `scrollTop` is `0`.
-- `scrollTop` doesn't respond to negative values; instead, it sets itself back to `0`.
-- If set to a value greater than the maximum available for the element, `scrollTop` settles itself to the maximum value.
+## Value
 
-When `scrollTop` is used on the root element (the `<html>` element), the `scrollY` of the window is returned. [This is a special case of `scrollTop`](https://www.w3.org/TR/2016/WD-cssom-view-1-20160317/#dom-element-scrolltop).
+A double-precision floating-point value indicating the number of pixels by which the element is currently scrolled vertically from the origin, where a positive value means the element is scrolled down (to reveal more content to the bottom). If the element isn't scrolled at all up or down, then `scrollTop` is 0. If the document is not the active document, the returned value is 0. If the document is rendered on a subpixel-precise device, then the returned value is also subpixel-precise and may contain a decimal component.
 
-> **Warning:** On systems using display scaling, `scrollTop` may give you a decimal value.
+It's possible for `scrollTop` to be negative if the element can be scrolled up from the initial containing block. For example, if the element's {{cssxref("flex-direction")}} is `column-reverse` and content grows upwards, then `scrollTop` is `0` when the scrollbar is at its bottommost position (at the start of the scrolled content), and then increasingly negative as you scroll towards the end of the content.
 
-## Value
+Safari responds to overscrolling by updating `scrollTop` beyond the maximum scroll position (unless the default "bounce" effect is disabled, such as by setting {{cssxref("overscroll-behavior")}} to `none`), while Chrome and Firefox do not. For example, `scrollTop` may be negative on Safari just by continuing to scroll up when the element is already at the top.
 
-A number.
+The `scrollTop` property can be set, which causes the element to scroll to the specified vertical position, in the same way as using {{domxref("Element.scroll()")}} with `behavior: "auto"`.
 
 ## Examples
 

diff --git a/files/en-us/web/api/window/scrollx/index.md b/files/en-us/web/api/window/scrollx/index.md
@@ -8,32 +8,23 @@ browser-compat: api.Window.scrollX
 
 {{ APIRef("CSSOM View") }}
 
-The read-only **`scrollX`** property of the
-{{domxref("Window")}} interface returns the number of pixels that the document is
-currently scrolled horizontally. This value is subpixel precise in modern browsers,
-meaning that it isn't necessarily a whole number. You can get the number of pixels the
-document is scrolled vertically from the {{domxref("Window.scrollY", "scrollY")}}
-property.
+The read-only **`scrollX`** property of the {{domxref("Window")}} interface returns the number of pixels by which the document is currently scrolled horizontally. This value is subpixel precise in modern browsers, meaning that it isn't necessarily a whole number. You can get the number of pixels the document is scrolled vertically from the {{domxref("Window.scrollY", "scrollY")}} property.
 
 ## Value
 
-In practice, the returned value is a double-precision floating-point value with the
-range of E(min)=-1022 to E(max)=1023 indicating the number of pixels the document is
-currently scrolled horizontally from the origin, where a positive value means the content
-is scrolled to the left. If the document is rendered on a subpixel-precise device, then
-the returned value is also subpixel-precise and may contain a decimal component. If the
-document isn't scrolled at all left or right, then `scrollX` is 0.
+A double-precision floating-point value indicating the number of pixels by which the document is currently scrolled horizontally from the origin, where a positive value means the content is scrolled to the right (to reveal more content to the right). In more technical terms, `scrollX` returns the X coordinate of the left edge of the current {{Glossary("viewport")}}. If the document isn't scrolled at all left or right, then `scrollX` is 0. If there is no viewport, the returned value is 0. If the document is rendered on a subpixel-precise device, then the returned value is also subpixel-precise and may contain a decimal component.
 
 > **Note:** If you need an integer value, you can use {{jsxref("Math.round()")}} to round it off.
 
-In more technical terms, `scrollX` returns the X coordinate of the left edge
-of the current {{Glossary("viewport")}}. If there is no viewport, the returned value is
-0\.
+It's possible for `scrollX` to be negative if the document can be scrolled to the left from the initial containing block. For example, if the document is right-to-left and content grows to the left.
+
+Safari responds to overscrolling by updating `scrollX` beyond the maximum scroll position (unless the default "bounce" effect is disabled, such as by setting {{cssxref("overscroll-behavior")}} to `none`), while Chrome and Firefox do not.
+
+This property is read-only. To scroll the window to a particular place, use {{domxref("Window.scroll()")}}.
 
 ## Examples
 
-This example checks the current horizontal scroll position of the document. If it's
-greater than 400 pixels, the window is scrolled back to the beginning.
+This example checks the current horizontal scroll position of the document. If it's greater than 400 pixels, the window is scrolled back to the beginning.
 
 ```js
 if (window.scrollX > 400) {
@@ -43,11 +34,7 @@ if (window.scrollX > 400) {
 
 ## Notes
 
-The `pageXOffset` property is an alias for the `scrollX` property:
-
-```js
-window.pageXOffset === window.scrollX; // always true
-```
+The `pageXOffset` property is an alias for the `scrollX` property. This means if you haven't re-assigned either property, `window.pageXOffset === window.scrollX` is always true.
 
 ## Specifications
 

diff --git a/files/en-us/web/api/window/scrolly/index.md b/files/en-us/web/api/window/scrolly/index.md
@@ -8,28 +8,17 @@ browser-compat: api.Window.scrollY
 
 {{APIRef("CSSOM View")}}
 
-The read-only **`scrollY`** property
-of the {{domxref("Window")}} interface returns the number of pixels that the document
-is currently scrolled vertically.
-
-This value is subpixel precise in modern
-browsers, meaning that it isn't necessarily a whole number. You can get the number of
-pixels the document is scrolled horizontally from the {{domxref("Window.scrollX", "scrollX")}} property.
+The read-only **`scrollY`** property of the {{domxref("Window")}} interface returns the number of pixels by which the document is currently scrolled vertically. This value is subpixel precise in modern browsers, meaning that it isn't necessarily a whole number. You can get the number of pixels the document is scrolled horizontally from the {{domxref("Window.scrollX", "scrollX")}} property.
 
 ## Value
 
-In practice, the returned value is a double-precision floating-point value with the range of
-2^(-1022) to 2^(+1023). It indicates the number of pixels the document is currently scrolled
-vertically from the origin, where a positive value means the content is scrolled to upward.
-If the document is rendered on a subpixel-precise device, then the returned value is also
-subpixel-precise and may contain a decimal component. If the document isn't scrolled at all
-up or down, then `scrollY` is 0.
+A double-precision floating-point value indicating the number of pixels by which the document is currently scrolled vertically from the origin, where a positive value means the content is scrolled down (to reveal more content to the bottom). In more technical terms, `scrollY` returns the Y coordinate of the top edge of the current {{Glossary("viewport")}}. If the document isn't scrolled at all top or down, then `scrollY` is 0. If there is no viewport, the returned value is 0. If the document is rendered on a subpixel-precise device, then the returned value is also subpixel-precise and may contain a decimal component.
 
 > **Note:** If you need an integer value, you can use {{jsxref("Math.round()")}} to round it off.
 
-In more technical terms, `scrollY` returns the Y coordinate of the top edge
-of the current {{Glossary("viewport")}}. If there is no viewport, the returned value is
-0\.
+Safari responds to overscrolling by updating `scrollY` beyond the maximum scroll position (unless the default "bounce" effect is disabled, such as by setting {{cssxref("overscroll-behavior")}} to `none`), while Chrome and Firefox do not. For example, `scrollY` may be negative on Safari just by continuing to scroll up when the document is already at the top.
+
+This property is read-only. To scroll the window to a particular place, use {{domxref("Window.scroll()")}}.
 
 ## Examples
 
@@ -49,12 +38,7 @@ relative scroll functions such as {{domxref("window.scrollBy", "scrollBy()")}},
 {{domxref("window.scrollByLines", "scrollByLines()")}}, or
 {{domxref("window.scrollByPages", "scrollByPages()")}}.
 
-The `pageYOffset` property is an alias for the `scrollY`
-property:
-
-```js
-window.pageYOffset === window.scrollY; // always true
-```
+The `pageYOffset` property is an alias for the `scrollY` property. This means if you haven't re-assigned either property, `window.pageYOffset === window.scrollY` is always true.
 
 ## Specifications