Add visual viewport scrollend event ref page #34427

chrisdavidmills · 2024-06-26T13:51:20Z

Description

Chrome 126 adds the onscrollend handler property. See the associated ChromeStatus entry. This PR adds a reference page for scrollend/onscrollend.

Motivation

Additional details

Related issues and pull requests

github-actions · 2024-06-26T14:00:47Z

Preview URLs

External URLs (1)

URL: /en-US/docs/Web/API/Visual_Viewport_API
Title: Visual Viewport API

https://mdn.github.io/dom-examples/visual-viewport-api/ (1 time) (Note! This may be a new URL 👀)

(comment last updated: 2024-08-27 10:23:44)

wbamberg · 2024-06-28T00:54:55Z

files/en-us/web/api/visual_viewport_api/index.md

@@ -18,7 +18,7 @@ The mobile web contains two viewports, the layout viewport and the visual viewpo

 What happens when a web page element needs to be visible on screen regardless of the visible portion of a web page? For example, what if you need a set of image controls to remain on screen regardless of the pinch zoom level of the device? Current browsers vary in how they handle this. The visual viewport lets web developers solve this by positioning elements relative to what's shown on screen.

-To access a window's visual viewport, you can obtain a {{domxref("VisualViewport")}} object from the {{domxref("window.visualViewport")}} property. The object includes a set of properties describing the viewport. It also adds two events, `onresize` and `onscroll`, that fire whenever the visual viewport changes. These events allow you to position elements relative to the visual viewport that would normally be anchored to the layout viewport.
+To access a window's visual viewport, you can obtain a {{domxref("VisualViewport")}} object from the {{domxref("window.visualViewport")}} property. The object includes a set of properties describing the viewport. It also adds three events, {{domxref("VisualViewport/resize_event", "resize")}}, {{domxref("VisualViewport/scroll_event", "scroll")}}, and {{domxref("VisualViewport/scrollend_event", "scrollend")}}, which fire whenever the visual viewport changes. These events allow you to position elements relative to the visual viewport that would normally be anchored to the layout viewport.


In the example below it says "You invoke this function by passing it to both event calls." - from what I can understand it we don't need to run this on scrollend (?) but should correct the language "both" anyway. And this sort of begs the question, when is scrollend useful?

I have updated that sentence to "viewportHandler() is passed in as a handler for the resize and scroll events." in my next commit.

I'll level with you though — I played with it quite a lot, but could not find a use case for scrollend.

OK, I've got some better information now. I've updated the text to talk more about real use cases and replaced the example on this page with a better, more understandable example.

The live demo link currently links to a Glitch instance, but I am more than happy to put it on dom-examples instead, once we get agreement that the demo is in a good state.

Can you point me to the actual code? I never know how to find it from a Glitch URL.

wbamberg · 2024-06-28T00:58:11Z

files/en-us/web/api/visualviewport/scrollend_event/index.md

+
+{{APIRef("Visual Viewport")}}
+
+The **`scrollend`** event of the {{domxref("VisualViewport")}} interface is fired when a scrolling operation on the visual viewport ends.


Would be great to have a sentence or two about why this event is useful: why I might want to listen to it and what I might want to do when it fires.

wbamberg · 2024-06-28T00:58:15Z

files/en-us/web/api/visualviewport/scrollend_event/index.md

+You can use the `scrollend` event in an {{domxref("EventTarget.addEventListener", "addEventListener()")}} method:
+
+```js
+visualViewport.addEventListener("scrollend", () => {
+  // …
+});
+```
+
+Or use the `onscrollend` event handler property:
+
+```js
+visualViewport.onscrollend = () => {
+  // …
+};
+```


These aren't useful examples, they really just show generic event syntax. Is there a somewhat realistic example we could have, that shows a use case?

See above. I'll ask the engineers at Google if they have an idea for a use case I could show.

Example added on the main visual viewport API page; I've linked to it from here rather than repeating it.

wbamberg

Yes, I like this example. I'd like it to be in dom-examples obviously, and had a few picky comments, but overall it makes sense to me.

wbamberg · 2024-08-01T03:36:52Z

files/en-us/web/api/visual_viewport_api/index.md

-The code below is based on [the sample in the specification](https://github.com/WICG/visual-viewport/blob/gh-pages/examples/fixed-to-viewport.html), though it adds a few things that make it function better. It shows a function called `viewportHandler()`. When called it queries the `offsetLeft` and `height` properties for values it uses in a CSS `translate()` method. You invoke this function by passing it to _both_ event calls.
+Our [Visual viewport events](https://visual-viewport-events.glitch.me/) example provides a basic demonstration of how the different visual viewport features work, including the three event types. Load the page in a supporting mobile browser and try pinch-zooming and panning around the boxes. On `resize` and `scroll`, the "Total" box is repositioned to keep the same position relative to the visual viewport. On `scrollend`, it updates to show which boxes are in view, and the sum of their numbers. A more complex application could use these techniques to scroll around map tiles and display relevant information for each one shown on the screen.
+
+The HTML and CSS for this example is fairly basic, and we won't explain it here for brevity. You can check it out at the example link above.


From the link given (https://visual-viewport-events.glitch.me/) I don't know how to see the HTML and CSS. If we don't explain it, we should link to it.

(actually, at least the HTML we should IMO quote because the JS does a lot of accessing the DOM elements)

I'll create a PR to add this demo to dom-examples after this, and update the links when it is merged.

In my next commit to this PR, I have added the HTML code listing, and a brief explanation of it.

wbamberg · 2024-08-01T03:40:31Z

files/en-us/web/api/visual_viewport_api/index.md

+
+```js
+const total = document.getElementById("total");
+let visibleBoxes = [];


Since this is "logically const" it might be better to declare it const and empty it by setting length to zero.

Yup, I agree with this; update made in my next commit.

wbamberg · 2024-08-01T03:41:19Z

files/en-us/web/api/visual_viewport_api/index.md

-      1 / viewport.scale
-    })`;
-  });
+function IsVisible(box) {


Suggested change

function IsVisible(box) {

function isVisible(box) {

Good catch. Updated.

wbamberg · 2024-08-01T03:41:49Z

files/en-us/web/api/visual_viewport_api/index.md

+  const x = box.offsetLeft,
+    y = box.offsetTop;
+  const right = x + box.offsetWidth,
+    bottom = y + box.offsetHeight;


Use separate declarations: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Writing_style_guide/Code_style_guide/JavaScript#variable_declarations

Good call; updated.

wbamberg · 2024-08-01T03:43:17Z

files/en-us/web/api/visual_viewport_api/index.md

+  const horLowerBound = window.scrollX + visualViewport.offsetLeft;
+  const horUpperBound =
+    window.scrollX + visualViewport.offsetLeft + visualViewport.width;
+  let hor =


Could be const? Also horizontal is a better name.

wbamberg · 2024-08-01T03:43:32Z

files/en-us/web/api/visual_viewport_api/index.md

+  const verLowerBound = window.scrollY + visualViewport.offsetTop;
+  const verUpperBound =
+    window.scrollY + visualViewport.offsetTop + visualViewport.height;
+  let ver =


Could be const? Also vertical is a better name.

wbamberg · 2024-08-01T03:43:58Z

files/en-us/web/api/visual_viewport_api/index.md

+  visibleBoxes = [];
+
+  for (const box of boxes) {
+    if (IsVisible(box)) {


Suggested change

if (IsVisible(box)) {

if (isVisible(box)) {

wbamberg · 2024-08-01T03:44:40Z

files/en-us/web/api/visual_viewport_api/index.md

+```js
+function updateSum() {
+  let sumTotal = 0;
+  let summands = [];


Suggested change

let summands = [];

const summands = [];

wbamberg · 2024-08-01T03:46:41Z

files/en-us/web/api/visual_viewport_api/index.md

@@ -18,7 +18,7 @@ The mobile web contains two viewports, the layout viewport and the visual viewpo

 What happens when a web page element needs to be visible on screen regardless of the visible portion of a web page? For example, what if you need a set of image controls to remain on screen regardless of the pinch zoom level of the device? Current browsers vary in how they handle this. The visual viewport lets web developers solve this by positioning elements relative to what's shown on screen.

-To access a window's visual viewport, you can obtain a {{domxref("VisualViewport")}} object from the {{domxref("window.visualViewport")}} property. The object includes a set of properties describing the viewport. It also adds two events, `onresize` and `onscroll`, that fire whenever the visual viewport changes. These events allow you to position elements relative to the visual viewport that would normally be anchored to the layout viewport.
+To access a window's visual viewport, you can obtain a {{domxref("VisualViewport")}} object from the {{domxref("window.visualViewport")}} property. The object includes a set of properties describing the viewport. It also adds three events, {{domxref("VisualViewport/resize_event", "resize")}}, {{domxref("VisualViewport/scroll_event", "scroll")}}, and {{domxref("VisualViewport/scrollend_event", "scrollend")}}, which fire whenever the visual viewport changes. These events allow you to position elements relative to the visual viewport that would normally be anchored to the layout viewport.


Can you point me to the actual code? I never know how to find it from a Glitch URL.

wbamberg · 2024-08-02T23:45:53Z

files/en-us/web/api/visual_viewport_api/index.md

+visualViewport.onscrollend = scrollendUpdater;
+window.onresize = scrollUpdater;
+window.onscroll = scrollUpdater;
+window.onscrollend = scrollendUpdater;


I don't understand why we have to listen to the Window events as well as the ``visualViewport` ones.

I added some explanation to the page to cover this:

Now we set event handler properties on both the visual viewport and the Window object to run the key functions at the appropriate times on both mobile and desktop:

We set the handlers on window so that the total box position and contents will update on conventional window scrolling operations, for example when you scroll the page on a desktop browser.

We set the handlers on visualViewport so that the total box position and contents will update on visual viewport scrolling/zooming operations, for example when you pinch-zoom and then scroll the page on a mobile browser.

chrisdavidmills · 2024-08-03T12:05:59Z

@wbamberg FYI, I've added the demo to the dom-examples repo in mdn/dom-examples#279.

chrisdavidmills · 2024-08-26T12:28:17Z

OK @wbamberg, the code explanation has been updated to match the dom-examples demo.

wbamberg

Thank you for the updates!

wbamberg · 2024-08-26T17:35:22Z

files/en-us/web/api/visual_viewport_api/index.md

@@ -32,42 +34,85 @@ To access a window's visual viewport, you can obtain a {{domxref("VisualViewport

 ## Examples

-The code below is based on [the sample in the specification](https://github.com/WICG/visual-viewport/blob/gh-pages/examples/fixed-to-viewport.html), though it adds a few things that make it function better. It shows a function called `viewportHandler()`. When called it queries the `offsetLeft` and `height` properties for values it uses in a CSS `translate()` method. You invoke this function by passing it to _both_ event calls.
+Our [Visual viewport events](https://visual-viewport-events.glitch.me/) example provides a basic demonstration of how the different visual viewport features work, including the three event types. Load the page in supporting desktop and mobile browsers and try scrolling around the displayed grid of boxes. Also try pinch-zooming on the mobile browser. On `resize` and `scroll`, the information box is repositioned to keep the same position relative to the visual viewport, and the viewport and scroll information it shows is updated. Also, on `resize` and `scroll` we change the box color to indicate something is happening, changing it back on `scrollend`.


This needs updating still (refers to glitch and grid of boxes).

Good call, I've updated both now.

wbamberg · 2024-08-26T17:36:31Z

files/en-us/web/api/visual_viewport_api/index.md

-The code below is based on [the sample in the specification](https://github.com/WICG/visual-viewport/blob/gh-pages/examples/fixed-to-viewport.html), though it adds a few things that make it function better. It shows a function called `viewportHandler()`. When called it queries the `offsetLeft` and `height` properties for values it uses in a CSS `translate()` method. You invoke this function by passing it to _both_ event calls.
+Our [Visual viewport events](https://visual-viewport-events.glitch.me/) example provides a basic demonstration of how the different visual viewport features work, including the three event types. Load the page in supporting desktop and mobile browsers and try scrolling around the displayed grid of boxes. Also try pinch-zooming on the mobile browser. On `resize` and `scroll`, the information box is repositioned to keep the same position relative to the visual viewport, and the viewport and scroll information it shows is updated. Also, on `resize` and `scroll` we change the box color to indicate something is happening, changing it back on `scrollend`.
+
+You'll find that on desktop browsers the {{domxref("Window.scrollX")}} and {{domxref("Window.scrollY")}} values are updated as the window is scrolled — the visual viewport position does not change. On mobile browsers however, the {{domxref("VisualViewport.offsetLeft")}} and {{domxref("VisualViewport.offsetTop")}} values are generally updated — it is usually the visual viewport that changes rather than the window position.


The text here and elsewhere seems to imply that pinch-zooming is only possible on mobile, but FWIW I find that pinch-zooming also works on the laptop trackpad.

I've updated these descriptions too.

files/en-us/web/api/visual_viewport_api/index.md

Co-authored-by: wbamberg <[email protected]>

chrisdavidmills · 2024-08-27T10:38:55Z

@wbamberg I also updated the dom-examples demo so that the HTML content is the same in both places (I tweaked the example HTML based on your comment about pinch-zoom): mdn/dom-examples#280

Can you merge that one too?

wbamberg

👍 thank you for your patience with me Chris.

chrisdavidmills · 2024-08-28T08:33:31Z

👍 thank you for your patience with me Chris.

@wbamberg from one grumpy Englishman to another, thank you so much for your excellent review!

Add visual viewport scrollend event ref page

73c51bb

chrisdavidmills requested a review from a team as a code owner June 26, 2024 13:51

chrisdavidmills requested review from wbamberg and removed request for a team June 26, 2024 13:51

github-actions bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Jun 26, 2024

correct scrollend linking errors

570dccc

wbamberg requested changes Jun 28, 2024

View reviewed changes

chrisdavidmills added 3 commits July 8, 2024 08:32

Merge branch 'main' into visualviewport-onscrollend

00f9bb6

Fix for wbamberg review comment

9d428a3

Added useful example and better use case explanations

96f5ad6

chrisdavidmills requested a review from wbamberg July 17, 2024 14:20

Merge branch 'main' into visualviewport-onscrollend

fbd2ad4

wbamberg requested changes Aug 2, 2024

View reviewed changes

chrisdavidmills added 2 commits August 3, 2024 12:47

fixes for wbamberg 2nd round review comments

63cd253

Merge branch 'main' into visualviewport-onscrollend

29907af

chrisdavidmills mentioned this pull request Aug 3, 2024

Add visual viewport API demo mdn/dom-examples#279

Merged

chrisdavidmills requested a review from wbamberg August 3, 2024 12:05

chrisdavidmills added 2 commits August 26, 2024 11:25

Merge branch 'main' into visualviewport-onscrollend

a095221

Update code explanation as the demo has changed

d42eddb

wbamberg requested changes Aug 26, 2024

View reviewed changes

chrisdavidmills and others added 3 commits August 27, 2024 10:36

Update files/en-us/web/api/visual_viewport_api/index.md

9a2af45

Co-authored-by: wbamberg <[email protected]>

Merge branch 'main' into visualviewport-onscrollend

1d2c7c4

Last few fixes for wbamberg comments

f62c7d3

chrisdavidmills requested a review from wbamberg August 27, 2024 10:27

chrisdavidmills mentioned this pull request Aug 27, 2024

Small tweak to visual viewport example wording mdn/dom-examples#280

Merged

wbamberg approved these changes Aug 27, 2024

View reviewed changes

wbamberg merged commit 4b5b3e1 into mdn:main Aug 27, 2024
8 checks passed

chrisdavidmills deleted the visualviewport-onscrollend branch August 28, 2024 08:32


		{{APIRef("Visual Viewport")}}

		The `scrollend` event of the {{domxref("VisualViewport")}} interface is fired when a scrolling operation on the visual viewport ends.

Add visual viewport scrollend event ref page #34427

Add visual viewport scrollend event ref page #34427

Conversation

chrisdavidmills commented Jun 26, 2024

Description

Motivation

Additional details

Related issues and pull requests

github-actions bot commented Jun 26, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wbamberg left a comment

Choose a reason for hiding this comment

wbamberg Aug 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills commented Aug 3, 2024

chrisdavidmills commented Aug 26, 2024

wbamberg left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

chrisdavidmills commented Aug 27, 2024 • edited Loading

wbamberg left a comment

Choose a reason for hiding this comment

chrisdavidmills commented Aug 28, 2024

github-actions bot commented Jun 26, 2024 •

edited

Loading

wbamberg Aug 1, 2024 •

edited

Loading

chrisdavidmills commented Aug 27, 2024 •

edited

Loading