CSS Scroll Snap Points Module Level 1

Motivating Examples

In this example, a series of images arranged in a scroll container are used to build a photo gallery. The scroll container is sized to the same size of the images contained therein. Using mandatory snap points, scrolling will always complete with a snap point aligned to the edge of the scroll container's visual viewport. By aligning a snap point at the edge of each image, this creates a photo viewer were users can scroll through the images one at a time.

        img {
            width:500px;
        }
        .photoGallery {
            width: 500px;
            overflow-x: auto;
            overflow-y: hidden;
            white-space: nowrap;
            /* Sets up points to which scrolling
               will snap along x-axis */
            scroll-snap-points-x: repeat(100%);
            /* Requires that scrolling always end at a snap point when
               the operation completes (hard snap) */
            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>
        

This example also builds a photo gallery as in example 1. However, 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 (such that a repeating snap interval would not be effective). Using mandatory element-based snap points, scrolling will always complete with an image centered in the scroll container's visual viewport.

            img {
                /* Defines the center of each photo as the
                   coordinate that should be used for snapping */
                scroll-snap-coordinate: 50% 50%;
            }
            .photoGallery {
                width: 500px;
                overflow-x: auto;
                overflow-y: hidden;
                white-space: nowrap;
                /* Specifies that each element's snap coordinate should
                   align with the center of the scroll container */
                scroll-snap-destination: 50% 50%;
                /* Requires that scrolling always end at a snap point
                   when the operation completes (hard snap). */
                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>
        

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 points instead of mandatory snap points 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 point, then the scroll will be adjusted to align the page as specified.

            .page {
                /* Defines the top center of each page as the
                   coordinate that should be used for snapping */
                scroll-snap-coordinate: 50% 0;
            }
            .docScroller {
                width: 500px;
                overflow-x: hidden;
                overflow-y: auto;
                /* Specifies that each element's snap coordinate should
                   align with the center of the scroll container, offset
                   a short distance from the top edge. */
                scroll-snap-destination: 50% 100px;
                 /* Encourages scrolling to end at a snap point when the
                    operation completes, if it is near a snap point */
                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>
        

Definitions

scroll container

An element which provides a scrolling user interface as described in [[!CSS21]], particularly in the section on overflow.

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

    Name: scroll-snap-type
    Value: none | mandatory | proximity
    Initial: none
    Applies to: scroll containers
    Inherited: no
    Percentages: n/a
    Media: interactive
    Computed value: specified value
    Animatable: no
    

none

The visual viewport of this scroll container must ignore snap points, if any, when scrolled.

mandatory

The visual viewport of this scroll container is guaranteed to rest on a snap point when there are no active scrolling operations. That is, it must come to rest on a snap point at the termination of a scroll, if possible. If the content changes such that the visual viewport would no longer rest on a snap point (e.g. content is added, moved, deleted, resized), the scroll offset must be modified to maintain this guarantee.

proximity

The visual viewport of this scroll container may come to rest on a snap point 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 point (e.g. content is added, moved, deleted, resized), the scroll offset may be modified to maintain this guarantee.

Scroll Snap Points: the 'scroll-snap-points-x' and 'scroll-snap-points-y' properties

    Name: scroll-snap-points-x, scroll-snap-points-y
    Value: none | repeat(<>)
    Initial: none
    Applies to: scroll containers
    Inherited: no
    Percentages: relative to same axis of the padding-box of the scroll container
    Media: interactive
    Computed value: specified value, with lengths made absolute
    Animatable: no
    

none

No snap points are defined by this scroll container. Contained elements may still define snap points on this scroll container's behalf.

repeat(<>)

Defines an interval at which snap points are defined, starting from the container's relevant start edge. Only positive lengths are allowed.

Scroll Snap Destination: the 'scroll-snap-destination' property

    Name: scroll-snap-destination
    Value: <>
    Initial: 0px 0px
    Applies to: scroll containers
    Inherited: no
    Percentages: relative to width and height of the padding-box of the scroll container
    Media: interactive
    Computed value: specified value, with lengths made absolute
    Animatable: yes
    

<>

Specifies the offset of the snap destination from the start edge of the scroll container's visual viewport. The first value gives the x coordinate of the snap destination, the second value its y coordinate.

Scroll Snap Coordinate: the 'scroll-snap-coordinate' property

How does this work with fragmentation?

Consider alternative naming besides "coordinate". Consider naming conventions like in Grid Layout for grouping properties on the container vs. items.

    Name: scroll-snap-coordinate
    Value: none | <>#
    Initial: none
    Applies to: all elements
    Inherited: no
    Percentages: refer to the element's border box
    Media: interactive
    Computed value: specified value, with lengths made absolute
    Animatable: yes
    

none

Specifies that this element does not contribute a snap point.

<>#

Specifies the offset of the snap coordinates from the start edge of the element's border box. For each pairing, the first value gives the x coordinate of the snap coordinate, the second value its y coordinate.

How can an alternative box be specified?

Acknowledgments