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>
        

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 margin 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>
        

scroll container

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

snap alignment container

A scroll container's snap alignment container is the rectangle obtained by reducing its visual viewport by its 'scroll-snap-padding'. Issue: Better name for this concept?

snap margin

An element's snap margin is the rectangle obtained by expanding its border box by its 'scroll-snap-margin'.

snap position

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.

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

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 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. When the visual viewport currently rests on a snap position, if the content changes such that the visual viewport would no longer rest on that 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) and if the user agent elects to modify the scroll offset to maintain snap position alignment, that same snap position must be satisfied after the content change.

    Name: scroll-snap-padding
    Value: [ <> | <> ]{1,4}
    Initial: 0
    Applies to: scroll containers
    Inherited: no
    Percentages: relative to the scroll container's visual viewport
    Media: interactive
    Computed value: as specified, with lengths made absolute
    Animatable: yes
    

[ <> | <> ]{1,4}

Specifies the region inset from the visual viewport. Values are interpreted as for 'padding', and specify inward offsets from each edge of the visual viewport.

    Name: scroll-snap-margin
    Value: <>{1,4}
    Initial: 0
    Applies to: all elements
    Inherited: no
    Percentages: n/a
    Media: interactive
    Computed value: as specified, with lengths made absolute
    Animatable: yes
    

<>{1,4}

Specifies the outset of the element's snap margin from the axis-aligned bounding box of the transformed border box, in the scroll container's coordinate space. Outsets are applied to this bounding box, not the border box. Note: This ensures that the scroll snap margin is always rectangular and axis-aligned to the scroll container's coordinate space.

    Name: scroll-snap-align
    Value: [ none | start | end | center ]{1,2}
    Initial: none
    Applies to: all elements
    Inherited: no
    Percentages: n/a
    Media: interactive
    Computed value: two keywords
    Animatable: no
    

none

This box does not define a snap position in the specified axis.

start

The scroll offset which aligns the start edge of this box's scroll snap margin with the start edge of its ancestor scroll container's region defined by 'scroll-snap-padding' in the specified axis is a snap position in that axis.

end

The scroll offset which aligns the end edge of this box's scroll snap margin with the end edge of its ancestor scroll container's region defined by 'scroll-snap-padding' in the specified axis is a snap position in that axis.

center

The scroll offset which aligns the center of this box's scroll snap margin with the center of its ancestor scroll container's region defined by 'scroll-snap-padding' in the specified axis is a snap position in that axis.