CSS Scroll Snap Points Module Level 1

Editor’s Draft, 11 January 2016

Editor’s Draft, 12 January 2016

This version: @@ -183,71 +241,67 @@ 1.2 example [CSS3VAL], when combined with this module, expands the definition of the <length> value type as used in this specification. 2. Motivating Examples - - In this example, a series of images arranged in a scroll container are used to build a photo gallery. In this example the scroll container is larger than the photos contained within (such that multiple images may be seen simultaneously), and the image + + In this example, a series of images arranged in a scroll container are used to build a photo gallery. In this example the scroll container is larger than the photos contained within (such that multiple images may be seen simultaneously), and the image sizes vary. Using mandatory element-based snap positions, scrolling will always complete with an image centered in the scroll container’s visual viewport. - img { - /* Specifies that the center of each photo - should align with the center of the scroll - container in the X axis when snapping */ - scroll-snap-align: center none; -} -.photoGallery { - width: 500px; - overflow-x: auto; - overflow-y: hidden; - white-space: nowrap; - /* Requires that the scroll offset always be - at a valid snap position when the scrolling - operation completes. */ - scroll-snap-type: mandatory; -} - - <div class="photoGallery"> - <img src="img1.jpg"> - <img src="img2.jpg"> - <img src="img3.jpg"> - <img src="img4.jpg"> - <img src="img5.jpg"> -</div> - + img { + /* Specifies that the center of each photo + should align with the center of the scroll + container in the X axis when snapping */ + scroll-snap-align: center none; +} +.photoGallery { + width: 500px; + overflow-x: auto; + overflow-y: hidden; + white-space: nowrap; + /* Requires that the scroll offset always be + at a valid snap position when the scrolling + operation completes. */ + scroll-snap-type: mandatory; +} + <div class="photoGallery"> + <img src="img1.jpg"> + <img src="img2.jpg"> + <img src="img3.jpg"> + <img src="img4.jpg"> + <img src="img5.jpg"> +</div> The layout of the scroll container’s contents in the example. The snap alignment container is represented by the red rectangle, and the snap area is represented by the yellow rectangle. Since the scroll-snap-align is "center" in the X axis, a snap position is established at each scroll offset which aligns the X-center of the snap alignment container (represented by a red dotted line) with the X-center of a snap area (represented by a yellow dotted line). - - This example builds a paginated document that aligns each page near to (but not exactly on) the edge of the scroll container. + + This example builds a paginated document that aligns each page near to (but not exactly on) the edge of the scroll container. This allows the previous page to "peek" in from above in order to make the user aware that they are not yet at the top of the document. Using proximity snap positions instead of mandatory snap positions allows the user to stop halfway through a page (rather than forcing them to snap one page at a time). However, if a scrolling operation would finish near a snap position, then the scroll will be adjusted to align the page as specified. - .page { - /* Defines the top of each page as the - edge that should be used for snapping */ - scroll-snap-align: none start; -} -.docScroller { - width: 500px; - overflow-x: hidden; - overflow-y: auto; - /* Specifies that each element’s snap area should - align with a 100px offset from the top edge. */ - scroll-snap-padding: 100px 0 0; - /* Encourages scrolling to end at a snap position when the - operation completes, if it is near a valid snap position */ - scroll-snap-type: proximity; -} - - <div class="docScroller"> - <div class="page">Page 1</div> - <div class="page">Page 2</div> - <div class="page">Page 3</div> - <div class="page">Page 4</div> -</div> - + .page { + /* Defines the top of each page as the + edge that should be used for snapping */ + scroll-snap-align: none start; +} +.docScroller { + width: 500px; + overflow-x: hidden; + overflow-y: auto; + /* Specifies that each element’s snap area should + align with a 100px offset from the top edge. */ + scroll-snap-padding: 100px 0 0; + /* Encourages scrolling to end at a snap position when the + operation completes, if it is near a valid snap position */ + scroll-snap-type: proximity; +} + <div class="docScroller"> + <div class="page">Page 1</div> + <div class="page">Page 2</div> + <div class="page">Page 3</div> + <div class="page">Page 4</div> +</div> The layout of the scroll container’s contents in the example. @@ -283,7 +337,7 @@ For a scroll container, a particular value for its scroll offset is a snap position if when scrolled to that offset the visual viewport of the scroll container would align with a descendent element in the manner specified by the scroll snap properties.: For a scroll container, a particular value for its scroll offset is a snap position if when scrolled to that offset the visual viewport of the scroll container would align with a descendent element in the manner specified by the scroll snap properties.

5. Scroll Snap Types: the scroll-snap-type property

The scroll-snap-type property defines how strictly a scroll container’s visual viewport should rest on snap positions. It intentionally does not specify nor mandate any precise animations or physics used to enforce those snap position; this is left up to the user agent.

Open issue on whether to enhance the scroll-snap-type property for specifying the axis or adding a second property. We have resolved that this functionality be added once the issue is resolved.

@@ -310,7 +364,7 @@

none
The visual viewport of this scroll container must ignore snap positions.
mandatory -
The visual viewport of this scroll container is guaranteed to rest on a snap position when there are no active scrolling operations. That is, it must come to rest on a snap position at the termination of a scroll, if a valid, reachable snap position exists. If no valid, reachable snap position exists then no snapping occurs. If the content changes such that the visual viewport would no longer rest on a snap position (e.g. content is added, moved, deleted, resized), the scroll offset must be modified to maintain this guarantee. +
+ The visual viewport of this scroll container is guaranteed to rest on a snap position when there are no active scrolling operations. That is, it must come to rest on a snap position at the termination of a scroll, if a valid, reachable snap position exists. If no valid, reachable snap position exists then no snapping occurs. +
If the content changes such that the visual viewport would no longer rest on a snap position (e.g. content is added, moved, deleted, resized), the scroll offset must be modified to maintain alignment of the visual viewport with a snap position. If the visual viewport was already aligned with a snap position prior to the content change and that snap position still exists (e.g. its associated element was not deleted), that same snap position must be satisfied after the content change.

proximity -
The visual viewport of this scroll container may come to rest on a snap position at the termination of a scroll at the discretion of the UA given the parameters of the scroll. If the content changes such that the visual viewport would no longer rest on a snap position (e.g. content is added, moved, deleted, resized), the scroll offset may be modified to maintain this guarantee. +
+ The visual viewport of this scroll container may come to rest on a snap position at the termination of a scroll at the discretion of the UA given the parameters of the scroll. +
If the content changes such that the visual viewport would no longer rest on a snap position (e.g. content is added, moved, deleted, resized), the scroll offset may be modified to maintain alignment of the visual viewport with a snap position. If the visual viewport was already aligned with a snap position prior to the content change and that snap position still exists (e.g. its associated element was not deleted) and if the user agent elects to modify the scroll offset to maintain snap position alignment, that same snap position should be satisfied after the content change.

6. Scroll Snap Padding: the scroll-snap-padding property

The scroll-snap-padding property defines the snap alignment container, a region inset from the visual viewport of a scroll container used in calculating its snap positions. The snap alignment container is used as the alignment container when calculating valid snap positions.
@@ -350,7 +408,7 @@
interactive

Computed value: -	specified value, with lengths made absolute +	as specified, with lengths made absolute
Animatable:	yes @@ -387,7 +445,7 @@ Pro	n/a	interactive	no -	specified value +	as specified
scroll-snap-padding	<length>{1,4} @@ -638,7 +696,7 @@ Pro	relative to the scroll container’s visual viewport	interactive	yes -	specified value, with lengths made absolute +	as specified, with lengths made absolute
scroll-snap-area	[ border-box \| margin-box ]? <length>{1,4} @@ -648,7 +706,7 @@ Pro	relative to the specified element box	interactive	yes -	specified value, with lengths made absolute +	as specified, with lengths made absolute
scroll-snap-align	[ none \| start \| end \| center ]{1,2}

Scroll Snap Types: the 'scroll-snap-type' property

Scroll Snap Padding: the 'scroll-snap-padding' property

CSS Scroll Snap Points Module Level 1

Editor’s Draft, 11 January 2016

Editor’s Draft, 12 January 2016

2. Motivating Examples

For a scroll container, a particular value for its scroll offset is a snap position if when scrolled to that offset the visual viewport of the scroll container would align with a descendent element in the manner specified by the scroll snap properties.

5. Scroll Snap Types: the scroll-snap-type property

6. Scroll Snap Padding: the scroll-snap-padding property

interactive

Pro

Pro

Pro