Editorial review: Add docs for scroll snap events #36057
Conversation
chrisdavidmills
requested review from
sideshowbarker
and removed request for
a team
github-actions
bot
added
Content:WebAPI
Preview URLs (15 pages)
Flaws (17)Note! 3 documents with no flaws that don't need to be listed. 🎉 URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
External URLs (11)URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
URL:
(comment last updated: 2024-10-11 14:47:25) |
github-actions
bot
added
Content:CSS
chrisdavidmills
changed the title
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
|
||
| In the JavaScript, we start by grabbing a reference to the `<main>` element and defining the number of `<section>` elements to generate (21), and a variable to begin counting from. We then use a [`while`](/en-US/docs/Web/JavaScript/Reference/Statements/while) loop to generate the `<section>` elements, giving each one an ID of `s` plus the current value of `n`, and a child [`h2`](/en-US/docs/Web/HTML/Element/Heading_Elements) with text that reads `Section` plus the current value of `n`. | ||
|
|
||
| ```js | ||
| const mainElem = document.querySelector("main"); | ||
| const sectionCount = 21; | ||
| let n = 1; | ||
|
|
||
| while (n <= sectionCount) { | ||
| mainElem.innerHTML += ` | ||
| <section id="s${n}"> | ||
| <h2>Section ${n}</h2> | ||
| </section> | ||
| `; | ||
| n++; | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Use static HTML (hidden). This way, we can remove this entire section.
There was a problem hiding this comment.
I don't agree with this. If I used static HTML, I'd still have to explain the structure of the <section> elements inside the HTML section, otherwise, the example wouldn't make sense. And then I'd have to add all 21 elements into the HTML, or find a way of hiding the full amount and just showing a single example, which would be awkward.
I'd rather keep it like this. It's not exactly a weird practice — people generate multiple HTML components all the time using frameworks.
There was a problem hiding this comment.
If this were in the JS / API section, i would not have suggested it. But in the CSS docs we avoid the el.style.x="y" and prefer class changes (keeping CSS out of the JS), and use static HTML. I was thinking that perhaps this guide is better served in the API docs anyhow. What do you think?
There was a problem hiding this comment.
Couple of things:
- I'm not doing any
el.style.x="y"in these examples. It is all class-based. - If I put it in the API docs, where would it go? It is part of the CSS Scroll Snap spec.
There was a problem hiding this comment.
How about https://codepen.io/estelle/pen/PoMZMMY. The example uses transitions rather than animations, and toggles the classes, and reduces the content the guide needs to explain to the event handlers and the very limited properties the event handlers are causing to change.
There was a problem hiding this comment.
The code is a bit shorter, but I don't think it is vastly simpler to explain. I also don't want to get rid of all my styling. I'm happy to hide the stuff that doesn't need explaining.
Tell you what, I will use a transition on the first example, like you've done, but I want to keep the animation on the second example, as it is useful to show how that could be handled. In more complex cases, people might want to use an animation.
| The HTML for the example is a single `<main>` element. We will add the `<section>` elements dynamically with JavaScript later on, to save on page space. | ||
|
|
||
| ```html | ||
| <main></main> | ||
| ``` |
There was a problem hiding this comment.
I disagree; see above.
|
|
||
| {{CSSRef}} | ||
|
|
||
| The [CSS Scroll Snap Module Level 2](drafts.csswg.org/css-scroll-snap-2) specification defines **scroll snap events**: {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} and {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}}. These make it easy to run JavaScript in response to the browser determining that a new snap target is pending, and when a new snap target is selected, respectively. |
There was a problem hiding this comment.
| The [CSS Scroll Snap Module Level 2](drafts.csswg.org/css-scroll-snap-2) specification defines **scroll snap events**: {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} and {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}}. These make it easy to run JavaScript in response to the browser determining that a new snap target is pending, and when a new snap target is selected, respectively. | |
| The [CSS scroll snap](en-US/docs/Web/CSS/CSS_scroll_snap) module defines two **scroll snap events**: {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} and {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}}. These enable running JavaScript in response to the browser determining that a new snap target is pending and when a new [scroll snap target](/en-US/docs/Web/CSS/CSS_scroll_snap/Basic_concepts) is selected, respectively. |
avoid "easy"
added "scroll" so i could link to the basic intro
There was a problem hiding this comment.
Good call. I've basically used your wording, except that I've cut down the two mentions of (scroll) snap target into one.
|
|
||
| The [CSS Scroll Snap Module Level 2](drafts.csswg.org/css-scroll-snap-2) specification defines **scroll snap events**: {{domxref("Element/scrollsnapchanging_event", "scrollsnapchanging")}} and {{domxref("Element/scrollsnapchange_event", "scrollsnapchange")}}. These make it easy to run JavaScript in response to the browser determining that a new snap target is pending, and when a new snap target is selected, respectively. | ||
|
|
||
| This article provides a guide to using these events, along with complete examples. |
There was a problem hiding this comment.
| This article provides a guide to using these events, along with complete examples. | |
| This guide provides an overview of these events, along with complete examples. |
|
|
||
| ## Events overview | ||
|
|
||
| The two events are set on a scrolling container that contains potential scroll snap targets, and are as follows: |
There was a problem hiding this comment.
| The two events are set on a scrolling container that contains potential scroll snap targets, and are as follows: | |
| Scroll snap events are set on a [scrolling container](/en-US/docs/Glossary/Scroll_container) that contains potential scroll snap targets. The events include: |
|
|
||
| - Try slowly scrolling the container up and down, without releasing the scrolling gesture, For example, drag your finger(s) on a touch screen device or trackpad, or hold down the mouse button on the scroll bar and move the mouse. You should see the boxes you move over turn a darker gray color, and then return to normal as you move away from them again. This is the `scrollsnapchanging` event in action. | ||
| - Now try releasing the scrolling gesture; the nearest box to your scrolling position should animate to a purple color, with white text. This is due to code run in response to the `scrollsnapchange` event firing. | ||
| - Last of all, try scrolling fast, for example by flicking your finger hard on the screen, to scroll past several potential targets before starting to come to rest near a target further down the scroll container. You should only see one `scrollsnapchanging` event fire as the scrolling starts to slow, before the `scrollsnapchange` event then fires and the selected snap target turns purple. |
There was a problem hiding this comment.
| - Last of all, try scrolling fast, for example by flicking your finger hard on the screen, to scroll past several potential targets before starting to come to rest near a target further down the scroll container. You should only see one `scrollsnapchanging` event fire as the scrolling starts to slow, before the `scrollsnapchange` event then fires and the selected snap target turns purple. | |
| - Last of all, try scrolling fast, for example by flicking your finger hard on the screen, to scroll past several potential targets before starting to come to rest near a target further down the scroll container. You should only see one `scrollsnapchanging` event fire as the scrolling starts to slow, before the `scrollsnapchange` event fires and the selected snap target turns purple. |
|
|
||
| ## The `SnapEvent` event object | ||
|
|
||
| Both of the above events share the same event object: {{domxref("SnapEvent")}}. This has two distinct properties that are key to how scroll snap events work: |
There was a problem hiding this comment.
| Both of the above events share the same event object: {{domxref("SnapEvent")}}. This has two distinct properties that are key to how scroll snap events work: | |
| Both of the above events share the {{domxref("SnapEvent")}} event object which has two distinct properties that are key to how scroll snap events work: |
There was a problem hiding this comment.
updated somewhat. I ended up with:
Both of the above events share the {{domxref("SnapEvent")}} event object. This has two properties that are key to how scroll snap events work:
Splitting into two sentences feels cleaner to read, to me.
|
|
||
| Both of the above events share the same event object: {{domxref("SnapEvent")}}. This has two distinct properties that are key to how scroll snap events work: | ||
|
|
||
| - {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} returns a reference to the element snapped to in the block direction when the event fired. |
There was a problem hiding this comment.
| - {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} returns a reference to the element snapped to in the block direction when the event fired. | |
| - {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} returns a reference to the element snapped to in the [block direction](/en-US/docs/Glossary/Flow_relative_values#block_direction) when the event fired. |
| Both of the above events share the same event object: {{domxref("SnapEvent")}}. This has two distinct properties that are key to how scroll snap events work: | ||
|
|
||
| - {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} returns a reference to the element snapped to in the block direction when the event fired. | ||
| - {{domxref("SnapEvent.snapTargetInline", "snapTargetInline")}} returns a reference to the element snapped to in the inline direction when the event fired. |
There was a problem hiding this comment.
| - {{domxref("SnapEvent.snapTargetInline", "snapTargetInline")}} returns a reference to the element snapped to in the inline direction when the event fired. | |
| - {{domxref("SnapEvent.snapTargetInline", "snapTargetInline")}} returns a reference to the element snapped to in the [inline direction](/en-US/docs/Glossary/Flow_relative_values#inline_direction) when the event fired. |
| - The {{domxref("Document/scrollsnapchange_event", "scrollsnapchange")}} event | ||
| - {{domxref("SnapEvent")}} |
There was a problem hiding this comment.
| - The {{domxref("Document/scrollsnapchange_event", "scrollsnapchange")}} event | |
| - {{domxref("SnapEvent")}} | |
| - {{domxref("Document/scrollsnapchange_event", "scrollsnapchange")}} event | |
| - {{domxref("SnapEvent")}} | |
| - {{domxref("SnapEvent.snapTargetBlock")}} | |
| - {{domxref("SnapEvent.snapTargetInline")}} |
There was a problem hiding this comment.
I'm not convinced these are really needed, when we already link to the event object?
|
Could you add a group for it in |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
files/en-us/web/css/css_scroll_snap/using_scroll_snap_events/index.md
Outdated
Show resolved
Hide resolved
files/en-us/web/css/css_scroll_snap/using_scroll_snap_events/index.md
Outdated
Show resolved
Hide resolved
files/en-us/web/css/css_scroll_snap/using_scroll_snap_events/index.md
Outdated
Show resolved
Hide resolved
files/en-us/web/css/css_scroll_snap/using_scroll_snap_events/index.md
Outdated
Show resolved
Hide resolved
files/en-us/web/css/css_scroll_snap/using_scroll_snap_events/index.md
Outdated
Show resolved
Hide resolved
| - : Returns a reference to the element snapped to in the block direction when the event fired, or `null` if no element is snapped to in the block direction. | ||
| - {{domxref("SnapEvent.snapTargetInline", "snapTargetInline")}} {{ReadOnlyInline}} {{Experimental_Inline}} | ||
| - : Returns a reference to the element snapped to in the inline direction when the event fired. | ||
| - : Returns a reference to the element snapped to in the inline direction when the event fired, or `null` if no element is snapped to in the inline direction. |
There was a problem hiding this comment.
in my tests, i get a reference to the first element. I haven't been able to get a null
There was a problem hiding this comment.
OK, was able to get a null, but only if there was no way to snap in the inline direction. If there is the possibility of inline scrolling as well as block scrolling, i get a value for both. If you can only scroll in one direction, the other direction is null.
It turns out, it is based on the value of scroll-snap-type:.
If the value is block, we get a value for snapTargetBlock.
if the value is inline, we get a value of snapTargetInline.
if the value is both, we get a value for both.
I think we need to clarify this.
There was a problem hiding this comment.
It's a really good idea to call this out explicitly. I've added an explanation of this on the SnapEvent page and on the scroll snap events guide page. I've also mentioned it on the snapTargetBlock/ snapTargetInline pages.
|
|
||
| - Try slowly scrolling the container up and down without releasing the scrolling gesture. For example, drag your finger(s) over the scrolling area on a touchscreen device or trackpad, or hold down the mouse button on the scroll bar and move the mouse. The boxes you move over should turn a darker gray color as you move over them, and then return to normal as you move away from them again. This is the `scrollsnapchanging` event in action. | ||
| - Now try releasing the scrolling gesture; the nearest box to your scrolling position should animate to a purple color, with white text. The animation occurs when the `scrollsnapchange` event fires. | ||
| - Finally try scrolling fast, for example by flicking your finger hard on the screen, to scroll past several potential targets before starting to come to rest near a target further down the scroll container. You should only see one `scrollsnapchanging` event fire as the scrolling starts to slow, before the `scrollsnapchange` event fires and the selected snap target turns purple. |
There was a problem hiding this comment.
| - Finally try scrolling fast, for example by flicking your finger hard on the screen, to scroll past several potential targets before starting to come to rest near a target further down the scroll container. You should only see one `scrollsnapchanging` event fire as the scrolling starts to slow, before the `scrollsnapchange` event fires and the selected snap target turns purple. | |
| - Finally, try scrolling fast. For example, try flicking your finger hard on the screen, to scroll past several potential targets before starting to come to rest near a target further down the scroll container. You should only see one `scrollsnapchanging` event fire as the scrolling starts to slow, before the `scrollsnapchange` event fires and the selected snap target turns purple. |
|
|
||
| Both of the above events share the {{domxref("SnapEvent")}} event object. This has two properties that are key to how scroll snap events work: | ||
|
|
||
| - {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} returns a reference to the element snapped to in the [block direction](/en-US/docs/Glossary/Flow_relative_values#block_direction) when the event fired, or `null` if no element is snapped to in the block direction (i.e. scroll snapping only occurs in the inline direction). |
There was a problem hiding this comment.
| - {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} returns a reference to the element snapped to in the [block direction](/en-US/docs/Glossary/Flow_relative_values#block_direction) when the event fired, or `null` if no element is snapped to in the block direction (i.e. scroll snapping only occurs in the inline direction). | |
| - {{domxref("SnapEvent.snapTargetBlock", "snapTargetBlock")}} returns a reference to the element snapped to in the [block direction](/en-US/docs/Glossary/Flow_relative_values#block_direction) when the event fired, or `null` if scroll snapping only occurs in the inline direction so no element is snapped to in the block direction. |
The i.e. confused me. I thought "as an example," but that we might get null in some cases in 2-dimensional. So suggesting this change (for every occurrence), but I may be wrong.
There was a problem hiding this comment.
Yeah, I think saying it this way round is easier to parse. Changed in all cases.
|
|
||
| ### Handling one-dimensional scrollers | ||
|
|
||
| If you are dealing with a horizontal scroller, only the event object's `snapTargetInline` property will change as the snapped element changes if the content has a horizontal {{cssxref("writing-mode")}}, or the `snapTargetBlock` property if the content has a vertical `writing-mode`. Conversely, if you are dealing with a vertical scroller, only the `snapTargetBlock` property will change as the snapped element changes if the content has a horizontal `writing-mode`, or the `snapTargetInline` property if the content has a vertical `writing-mode`. In each case, the non-changing property of the two returns `null`. |
There was a problem hiding this comment.
| If you are dealing with a horizontal scroller, only the event object's `snapTargetInline` property will change as the snapped element changes if the content has a horizontal {{cssxref("writing-mode")}}, or the `snapTargetBlock` property if the content has a vertical `writing-mode`. Conversely, if you are dealing with a vertical scroller, only the `snapTargetBlock` property will change as the snapped element changes if the content has a horizontal `writing-mode`, or the `snapTargetInline` property if the content has a vertical `writing-mode`. In each case, the non-changing property of the two returns `null`. | |
| If you are dealing with a horizontal scroller, only the event object's `snapTargetInline` property will change as the snapped element changes if the content has a horizontal {{cssxref("writing-mode")}}, or the `snapTargetBlock` property if the content has a vertical `writing-mode`. Conversely, if you are dealing with a vertical scroller, only the `snapTargetBlock` property will change as the snapped element changes if the content has a horizontal `writing-mode`, or the `snapTargetInline` property if the content has a vertical `writing-mode`. In each case, the non-changing property of the two returns in a one-dimensional scroller always returns `null`. |
There was a problem hiding this comment.
I wasn't sure about this. We are talking about one-dimensional scrollers in this section. I've updated the two-dimensional scroller section to say that in that case, both properties return an element reference, and neither returns null, to provide a more obvious contrast.
There was a problem hiding this comment.
sorry for leaving that in. I edited this before I realized that it has nothing to do with "one dimensional", but rather has to do with the property value of inline, block, or both.
|
|
||
| If the values are different, it means that the scroller has been scrolled in that direction (block or inline), and we log a message to console to indicate this. In a real example, you'd likely style the snapped element in some way to indicate that it has been snapped to. | ||
|
|
||
| We then update the values of `prevState.snapTargetBlock` and `prevState.snapTargetInline`, ready for the next time the event handler is run. |
There was a problem hiding this comment.
| We then update the values of `prevState.snapTargetBlock` and `prevState.snapTargetInline`, ready for the next time the event handler is run. | |
| We then update the values of `prevState.snapTargetBlock` and `prevState.snapTargetInline` for the next time the event handler is run. |
There was a problem hiding this comment.
I'm not sure about this one. I've had a think, and ended up updating it to:
We then update the values of
prevState.snapTargetBlockandprevState.snapTargetInlineready for when the event handler next runs.
| } | ||
| ``` | ||
|
|
||
| Each `<section>` element is given a {{cssxref("margin")}} of `50px` to separate out the `<section>` elements and make the scroll snapping behavior a bit easier to experience. We then set {{cssxref("scroll-snap-align")}} to `center`, to specify that we want to snap to the center of each snap target. Finally, we apply a {{cssxref("transition")}} to smoothly animate to and from the style changes applied when a snap target selection has been made or is pending. |
There was a problem hiding this comment.
| Each `<section>` element is given a {{cssxref("margin")}} of `50px` to separate out the `<section>` elements and make the scroll snapping behavior a bit easier to experience. We then set {{cssxref("scroll-snap-align")}} to `center`, to specify that we want to snap to the center of each snap target. Finally, we apply a {{cssxref("transition")}} to smoothly animate to and from the style changes applied when a snap target selection has been made or is pending. | |
| Each `<section>` element is given a {{cssxref("margin")}} of `50px` to separate out the `<section>` elements and make the scroll snapping behavior a bit more apparent. We then set {{cssxref("scroll-snap-align")}} to `center`, to specify that we want to snap to the center of each snap target. Finally, we apply a {{cssxref("transition")}} to smoothly animate to and from the style changes applied when a snap target selection has been made or is pending. |
There was a problem hiding this comment.
Updated. I got rid of "a bit" too.
|
|
||
| ### JavaScript | ||
|
|
||
| In the JavaScript, we start by grabbing a reference to the `<main>` element and defining the number of `<section>` elements to generate (21), and a variable to begin counting from. We then use a [`while`](/en-US/docs/Web/JavaScript/Reference/Statements/while) loop to generate the `<section>` elements, giving each one a child [`h2`](/en-US/docs/Web/HTML/Element/Heading_Elements) with text that reads `Section` plus the current value of `n`. |
There was a problem hiding this comment.
| In the JavaScript, we start by grabbing a reference to the `<main>` element and defining the number of `<section>` elements to generate (21), and a variable to begin counting from. We then use a [`while`](/en-US/docs/Web/JavaScript/Reference/Statements/while) loop to generate the `<section>` elements, giving each one a child [`h2`](/en-US/docs/Web/HTML/Element/Heading_Elements) with text that reads `Section` plus the current value of `n`. | |
| In the JavaScript, we start by grabbing a reference to the `<main>` element and defining the number of `<section>` elements to generate and a variable to begin counting from. We then use a [`while`](/en-US/docs/Web/JavaScript/Reference/Statements/while) loop to generate the `<section>` elements, giving each one a child [`h2`](/en-US/docs/Web/HTML/Element/Heading_Elements) with text that reads `Section` plus the current value of `n`. |
There was a problem hiding this comment.
or, "generate (in this case, 21) and...". No comma needed before the "and"
There was a problem hiding this comment.
yeah, that works nicely. Updated.
| ``` | ||
|
|
||
| > [!NOTE] | ||
| > We don't need to worry about the `snapTargetInline` event object property for this demo — we are only scrolling vertically and the demo is using a horizontal writing mode, therefore only the `snapTargetBlock` value will change. `snapTargetInline` will always return `null`. |
There was a problem hiding this comment.
| > We don't need to worry about the `snapTargetInline` event object property for this demo — we are only scrolling vertically and the demo is using a horizontal writing mode, therefore only the `snapTargetBlock` value will change. `snapTargetInline` will always return `null`. | |
| > We don't need to worry about the `snapTargetInline` event object property for this demo — we are only scrolling vertically and the demo is using a horizontal writing mode, therefore only the `snapTargetBlock` value will change. In this case, `snapTargetInline` will always return `null`. |
|
|
||
| ### CSS | ||
|
|
||
| ```css hidden |
There was a problem hiding this comment.
optional, but if you encase all the hidden css in a layer:
@layer {
/* put hidden css here */
}
You can then move the layer / hidden CSS to after the visible css in the guide.
That ways, if and when the reader hits "play", the relevant CSS will be at the top
There was a problem hiding this comment.
This is not a habit I want to get into. I don't think it is that big a deal making a web developer search through a small stylesheet, and it complicates the CSS unnecessarily.
| 80% { | ||
| background: #eee; | ||
| color: black; | ||
| opacity: 0; |
There was a problem hiding this comment.
| opacity: 0; | |
| opacity: 0.1; |
let's not fully hide it.
There was a problem hiding this comment.
I've changed it, but I don't really see why you are suggesting this change — it makes very little difference to the look and feel. What is your reasoning here?
There was a problem hiding this comment.
I don't want to suggest to a dev that it's ever good practice to make content disappear (unless you actually want to end up on display none)
|
|
||
| ### JavaScript | ||
|
|
||
| In the JavaScript, we start off in the same way as with the previous example, except that this time we generate 49 `<section>` elements, and we give each one an ID of `s` plus the current value of `n` to help track them later on. With the grid layout we specified above, this gives us seven columns of seven `<section>`s. |
There was a problem hiding this comment.
| In the JavaScript, we start off in the same way as with the previous example, except that this time we generate 49 `<section>` elements, and we give each one an ID of `s` plus the current value of `n` to help track them later on. With the grid layout we specified above, this gives us seven columns of seven `<section>`s. | |
| In the JavaScript, we start off in the same way as with the previous example, except that this time we generate 49 `<section>` elements, and we give each one an ID of `s` plus the current value of `n` to help track them later on. With the grid layout we specified above, we will have seven columns of seven `<section>`s. |
just to make it not sound like the js is giving us the grid
@Josh-Cena we could do, but I'd rather not. It is part of the CSS Scroll Snap Module and very closely related to the other features available there. Having another landing page for it IMO would confuse matters and also possibly have negative SEO effects. Also, we are effectively talking about an interface and two events. If it was significantly more content, I'd be a bit more inclined to agree. |
|
OK; perhaps it should be possible for APIRef sidebars to have CSS modules as landing pages. But that's for a future discussions |
And to be able to list guides from elsewhere in the guides list. Certainly worth considering in the future. |
Description
Chrome 129 supports scroll snap events —
scrollsnapchangeandscrollsnapchanging, which enable code being fired in response to a new scroll snap target being snapped to, and the browser identifying a change in the next snap target to be snapped to (if the gesture were to end).See the associated ChromeStatus entry and the Scroll Snap Events blog post for more context and a guide.
This PR adds:
Element, but I've also put short pages for the events hanging offDocumentandWindow, which link to theElementversions for the full details. See https://drafts.csswg.org/css-scroll-snap-2/#event-handlers-on-elements-document-and-window-objects.SnapEventevent objectMotivation
Additional details
Related issues and pull requests