CSS: scroll-snap module (mdn#23428)

* Deprecated inline * Added glossary section. Removed BCD * added see also * Reorganize spec landing page * expand guide and add gotchas * Apply suggestions from code review Co-authored-by: Dipika Bhattacharya <[email protected]> Co-authored-by: Dipika Bhattacharya <[email protected]>
teoli2003 · Jan 11, 2023 · ac3538d · ac3538d
1 parent 16e4af4
commit ac3538d
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 40 deletions.
diff --git a/files/en-us/web/css/css_scroll_snap/basic_concepts/index.md b/files/en-us/web/css/css_scroll_snap/basic_concepts/index.md
@@ -11,16 +11,16 @@ tags:
 
 {{CSSRef}}
 
-The [CSS Scroll Snap specification](https://drafts.csswg.org/css-scroll-snap-1/) gives us a way to snap scrolling to certain points as the user scrolls through a document. This can be helpful in creating a more app-like experience on mobile or even on the desktop for some types of applications.
+The [CSS Scroll Snap](/en-US/docs/Web/CSS/CSS_Scroll_Snap) feature provides a way to snap the scrolling to certain points as the user scrolls through a document. This can be helpful in creating a more app-like experience on mobile or even on the desktop for some types of applications.
 
 ## Key properties for CSS Scroll Snap
 
-The key properties of the Scroll Snap specification are:
+The key properties for the scroll snap feature are:
 
-- {{CSSxRef("scroll-snap-type")}}: This property is used on the [scroll container](/en-US/docs/Glossary/Scroll_container) to state the type and direction of scrolling.
-- {{CSSxRef("scroll-snap-align")}}: This property must be used on child elements in order to set the position that scrolling will snap to.
+- {{CSSxRef("scroll-snap-type")}}: This property is used on the [scroll container](/en-US/docs/Glossary/Scroll_container) to specify the type, direction, and optionality of scrolling.
+- {{CSSxRef("scroll-snap-align")}}: This property is used on child elements to specify the scroll snap position.
 
-The example below demonstrates scroll snapping along the vertical axis, which is defined by `scroll-snap-type`. Additionally, `scroll-snap-align` is used on the section element to dictate the point where the scrolling should stop.
+The example below demonstrates scroll snapping along the vertical axis, which is defined by `scroll-snap-type`. Additionally, `scroll-snap-align` is used on all the `<section>` element children dictating the point where the scrolling of each child should stop.
 
 {{EmbedGHLiveSample("css-examples/scroll-snap/mandatory-y.html", '100%', 700)}}
 
@@ -30,35 +30,41 @@ The {{CSSxRef("scroll-snap-type")}} property needs to know the direction in whic
 
 You can also pass in the keywords `mandatory` or `proximity`. The `mandatory` keyword tells the browser whether the content _has_ to snap to a certain point, no matter where the scroll is. The `proximity` keyword means that the content may snap to the point, but does not have to.
 
-Using `mandatory` gives a very consistent experience — you know that the browser will always snap to each defined point. This means you can be confident that something you expect to be at the top of the screen will be when scrolling finishes. However, it can cause problems if the content is larger than you expect — users may find themselves in the frustrating position of never being able to scroll and view a certain point in the content. Therefore, use of mandatory should be carefully considered and only used in situations where you know how much content is on the screen at any one time.
+Using `mandatory` creates a very consistent scrolling experience — you know that the browser will always snap to each defined point. This means that you can be confident that something you expect to be at the top of the screen will be when scrolling finishes. However, it can cause problems if the content is larger than you expect — users may find themselves in the frustrating position of never being able to scroll and view a certain point in the content. Therefore, use of `mandatory` should be carefully considered and only used in situations where you know how much content is on the screen at any time.
+
+> **Note:** Never use `mandatory` if the content inside one of your child elements will overflow the parent container because the overflowing content will not be visible.
 
 The `proximity` value will only snap to a position when it is close by, the exact distance being left to the browser to decide.
 
 In the example below, you can change the value between `mandatory` and `proximity` to see the effect this has on the scroll experience.
 
 {{EmbedGHLiveSample("css-examples/scroll-snap/mandatory-proximity.html", '100%', 700)}}
 
+In the above example, both {{cssxref("height", "height: 300px;")}} and {{cssxref("overflow-y", "overflow-y: scroll;")}} are set on the scroll container. If the contents don't overflow their container, there is nothing to scroll.
+
 ## Using scroll-snap-align
 
-The {{CSSxRef("scroll-snap-align")}} property can take a value of `start`, `end`, or `center` — indicating the point the content should snap to in the scroll container. In the example below, you can change the value of `scroll-snap-align` to see how this changes the scroll behavior.
+The valid values for the {{CSSxRef("scroll-snap-align")}} property include `start`, `end`, `center`, and `none`. These values are used to indicate the point in the scroll container to which the content should snap. In the example below, you can change the value of `scroll-snap-align` to see how this changes the scroll behavior.
 
 {{EmbedGHLiveSample("css-examples/scroll-snap/align.html", '100%', 700)}}
 
+If `scroll-snap-type` is `mandatory` and `scroll-snap-align` on a child is either set to `none` or not set (in which case, it defaults to `none`), the user will be unable to scroll that element into view.
+
 ## Using scroll-padding
 
-If you do not want the content to snap right to the edge of the scroll container, you can use the {{CSSxRef("scroll-padding")}} property or its equivalent longhand values to set some padding.
+If you do not want the content to snap right to the edge of the scroll container, you can use the {{CSSxRef("scroll-padding")}} property or its equivalent longhand values to add some padding.
 
-In the below example, `scroll-padding` is set to 40 pixels. When the content snaps to the start of the second and third sections, the scrolling stops 40 pixels away from the start of the section. Try changing the `scroll-padding` value to see how this changes the distance.
+In the example below, `scroll-padding` is set to `40px`. When the content snaps to the start of the second and third sections, scrolling stops 40 pixels away from the start of the section. Try changing the `scroll-padding` value to see how this changes the distance.
 
 {{EmbedGHLiveSample("css-examples/scroll-snap/scroll-padding.html", '100%', 700)}}
 
-This is potentially useful if you have a fixed element, for example a navigation bar, which could end up overlapping scrolled content. By using `scroll-padding`, you can reserve a space for it as in the example below where the `<h1>` remains on screen as the content scrolls beneath it. Without padding, the heading would overlap some of the content when snapping happens.
+This is potentially useful if you have a [fixed](/en-US/docs/Web/CSS/position#fixed_positioning) element, for example a navigation bar, which could end up overlapping scrolled content. By using `scroll-padding`, you can reserve a space for the fixed element, as shown in the example below, where the `<h1>` element remains on screen as the content scrolls beneath it. Without padding, the heading would overlap some of the content when snapping happens.
 
 {{EmbedGHLiveSample("css-examples/scroll-snap/scroll-padding-sticky.html", '100%', 700)}}
 
 ## Using scroll-margin
 
-The {{CSSxRef("scroll-margin")}} property can be set on child elements, essentially defining an outset from the defined box. This allows for different amounts of space for different child elements, and can be used in conjunction with `scroll-padding` on the parent. Try this in the example below.
+The {{CSSxRef("scroll-margin")}} property or the longhand scroll margin values can be set on child elements, essentially defining an outset from the defined box. This allows for different amounts of space for different child elements and can be used in conjunction with `scroll-padding` on the parent. Try this in the example below.
 
 {{EmbedGHLiveSample("css-examples/scroll-snap/scroll-margin.html", '100%', 700)}}
 
@@ -68,6 +74,9 @@ The {{CSSxRef("scroll-snap-stop")}} property tells the browser whether it should
 
 It could be helpful in ensuring users see each section of the scroller and don't accidentally zip past them. However, it could be problematic in making the scrolling experience slower if the user is looking for a particular section.
 
-## Browser compatibility
+## See also
 
-The individual property pages detail the browser compatibility situation for Scroll Snap.
+- [Well-controlled scrolling with CSS Scroll Snap](https://web.dev/css-scroll-snap/)
+- [Practical CSS scroll snapping/](https://css-tricks.com/practical-css-scroll-snapping/)
+- [CSS Scroll Snap](https://12daysofweb.dev/2022/css-scroll-snap/)
+- [Scroll snap examples on Codepen](https://codepen.io/collection/KpqBGW)
diff --git a/files/en-us/web/css/css_scroll_snap/index.md b/files/en-us/web/css/css_scroll_snap/index.md
@@ -13,41 +13,54 @@ spec-urls: https://drafts.csswg.org/css-scroll-snap/
 
 {{CSSRef}}
 
-**CSS Scroll Snap** is a module of CSS that introduces scroll snap positions, which enforce the scroll positions that a {{Glossary("scroll container")}}'s {{Glossary("scrollport")}} may end at after a scrolling operation has completed.
+**CSS Scroll Snap** is a module of CSS that contains features to control panning and scrolling behavior with snap positions.
+
+## Key concepts
+
+CSS scroll snap enables snapping content as the user scrolls overflowing content within a {{Glossary("scroll container")}}. Scroll snap introduces scroll snap positions, which enforce the scroll positions that a scroll container's {{Glossary("scrollport")}} may end at after a scrolling operation has completed.
+
+To enable scroll snapping, the scrolling behavior is defined on the scroll container. The container's {{cssxref("scroll-snap-type")}} property defines whether the scrollable viewport can be snapped to, the axis upon which the snapping occurs, and whether snapping is required or optional. To enable scrolling, the container should have a defined size and {{cssxref("overflow")}} must be enabled. There are optional {{cssxref("scroll-padding")}} properties that can be set on the scroll container to create a snapping offset.
+
+The {{cssxref("scroll-snap-align")}} property is set on every child of the scroll container, defining each child's snap position or lack thereof. The {{cssxref("scroll-snap-stop")}} property enables requiring that child is snapped to during scrolling and not passed over. There are several {{cssxref("scroll-margin")}} properties that can be set on the snapped-to child elements to create an outset from the defined box.
 
 ## Reference
 
 ### Properties on containers
 
 - {{cssxref("scroll-snap-type")}}
 - {{cssxref("scroll-padding")}}
-- {{cssxref("scroll-padding-top")}}
-- {{cssxref("scroll-padding-right")}}
-- {{cssxref("scroll-padding-bottom")}}
-- {{cssxref("scroll-padding-left")}}
-- {{cssxref("scroll-padding-inline")}}
-- {{cssxref("scroll-padding-inline-start")}}
-- {{cssxref("scroll-padding-inline-end")}}
-- {{cssxref("scroll-padding-block")}}
-- {{cssxref("scroll-padding-block-start")}}
-- {{cssxref("scroll-padding-block-end")}}
+ - {{cssxref("scroll-padding-top")}}
+ - {{cssxref("scroll-padding-right")}}
+ - {{cssxref("scroll-padding-bottom")}}
+ - {{cssxref("scroll-padding-left")}}
+ - {{cssxref("scroll-padding-inline")}}
+ - {{cssxref("scroll-padding-inline-start")}}
+ - {{cssxref("scroll-padding-inline-end")}}
+ - {{cssxref("scroll-padding-block")}}
+ - {{cssxref("scroll-padding-block-start")}}
+ - {{cssxref("scroll-padding-block-end")}}
 
 ### Properties on children
 
 - {{cssxref("scroll-snap-align")}}
 - {{cssxref("scroll-margin")}}
-- {{cssxref("scroll-margin-top")}}
-- {{cssxref("scroll-margin-right")}}
-- {{cssxref("scroll-margin-bottom")}}
-- {{cssxref("scroll-margin-left")}}
-- {{cssxref("scroll-margin-inline")}}
-- {{cssxref("scroll-margin-inline-start")}}
-- {{cssxref("scroll-margin-inline-end")}}
-- {{cssxref("scroll-margin-block")}}
-- {{cssxref("scroll-margin-block-start")}}
-- {{cssxref("scroll-margin-block-end")}}
+ - {{cssxref("scroll-margin-top")}}
+ - {{cssxref("scroll-margin-right")}}
+ - {{cssxref("scroll-margin-bottom")}}
+ - {{cssxref("scroll-margin-left")}}
+ - {{cssxref("scroll-margin-inline")}}
+ - {{cssxref("scroll-margin-inline-start")}}
+ - {{cssxref("scroll-margin-inline-end")}}
+ - {{cssxref("scroll-margin-block")}}
+ - {{cssxref("scroll-margin-block-start")}}
+ - {{cssxref("scroll-margin-block-end")}}
 - {{cssxref("scroll-snap-stop")}}
 
+### Glossary terms
+
+- {{Glossary("scroll container")}}
+- {{Glossary("scrollport")}}
+
 ## Guides
 
 - [Basic concepts of CSS Scroll Snap](/en-US/docs/Web/CSS/CSS_Scroll_Snap/Basic_concepts)
@@ -56,6 +69,9 @@ spec-urls: https://drafts.csswg.org/css-scroll-snap/
 
 {{Specifications}}
 
-## Browser compatibility
+## See also
 
-The individual property pages detail browser compatibility information for each property.
+- [Well-controlled scrolling with CSS Scroll Snap](https://web.dev/css-scroll-snap/)
+- [Practical CSS scroll snapping/](https://css-tricks.com/practical-css-scroll-snapping/)
+- [CSS Scroll Snap](https://12daysofweb.dev/2022/css-scroll-snap/)
+- [Scroll snap examples on Codepen](https://codepen.io/collection/KpqBGW)
diff --git a/files/en-us/web/css/css_scroll_snap_points/index.md b/files/en-us/web/css/css_scroll_snap_points/index.md
@@ -21,10 +21,10 @@ spec-urls: https://drafts.csswg.org/css-scroll-snap/
 
 ### Properties
 
-- {{cssxref("scroll-snap-coordinate")}}
-- {{cssxref("scroll-snap-destination")}}
-- {{cssxref("scroll-snap-points-x")}}
-- {{cssxref("scroll-snap-points-y")}}
+- {{cssxref("scroll-snap-coordinate")}} {{Deprecated_Inline}}
+- {{cssxref("scroll-snap-destination")}} {{Deprecated_Inline}}
+- {{cssxref("scroll-snap-points-x")}} {{Deprecated_Inline}}
+- {{cssxref("scroll-snap-points-y")}} {{Deprecated_Inline}}
 - {{cssxref("scroll-snap-type")}}
 
 ## Specifications