Overview.bs

<pre class="metadata">
Title: CSS Scroll Snap Points Module Level 1
Group: csswg
Shortname: css-snappoints
TR: http://www.w3.org/TR/css-snappoints-1/
Level: 1
Status: ED
Work Status: Exploring
ED: http://dev.w3.org/csswg/css-snappoints/
Editor: Matt Rakow, Microsoft
Editor: Jacob Rossi, Microsoft
Abstract: This module contains features to control panning and scrolling behavior with "snap positions".
Ignored Terms: scroll-snap-positions-*, containing block chain
</pre>

Issue: <b>This spec is currently undergoing major changes in line with the resolutions in <a href="https://lists.w3.org/Archives/Public/www-style/2015Dec/0048.html">https://lists.w3.org/Archives/Public/www-style/2015Dec/0048.html</a>. During this process it is not safe to assume that the current form will be representative of what it will look like in the future. After the work in process is completed, it will closely resemble <a href="https://drafts.csswg.org/css-scroll-snap/">this proposal</a>.</b>

Introduction {#intro}
=====================

    <em>This section is not normative.</em>

    Popular UX paradigms for scrollable content frequently employ paging through content,
    or sectioning into logical divisions.
    This is especially true for touch interactions
    where it is quicker and easier for users to quickly pan through a flatly-arranged breadth of content
    rather than delving into a heirarchical structure through tap navigation.
    For example, it is easier for a user to view many photos in a photo album
    by panning through a photo slideshow view
    rather than tapping on individual photos in an album.

    However, given the imprecise nature of scrolling inputs
    like touch panning and mousewheel scrolling,
    it is difficult for web developers to guarantee a well-controlled scrolling experience,
    in particular creating the effect of paging through content.
    For instance, it is easy for a user to land at an awkward scroll offset
    which leaves a page partially on-screen when panning.

    To this end, we introduce scroll snap positions
    which enforce the scroll offsets that a <a>scroll container's</a> visual viewport may end at
    after a scrolling operation has completed.

Module interactions {#placement}
--------------------------------

    This module extends the scrolling user interface features defined in [[!CSS21]] section 11.1.

    None of the properties in this module apply to the ''::first-line'' and ''::first-letter'' pseudo-elements.

Values {#values}
----------------

    This specification follows the
    <a href="http://www.w3.org/TR/CSS21/about.html#property-defs">CSS property
    definition conventions</a> from [[!CSS21]]. Value types not defined in
    this specification are defined in CSS Level 2 Revision 1 [[!CSS21]].
    Other CSS modules may expand the definitions of these value types: for
    example [[CSS3VAL]], when combined with this module, expands the
    definition of the <<length>> value type as used in this specification.

Motivating Examples {#examples}
===============================

    <div class="example">
        In this example, a series of images arranged in a <a>scroll container</a>
        are used to build a photo gallery.  In this example the <a>scroll container</a>
        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 <a>scroll container's</a> visual viewport.

        <pre class="lang-css">
            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;
            }
        </pre>

        <pre class="lang-html">
            &lt;div class="photoGallery">
                &lt;img src="img1.jpg">
                &lt;img src="img2.jpg">
                &lt;img src="img3.jpg">
                &lt;img src="img4.jpg">
                &lt;img src="img5.jpg">
            &lt;/div>
        </pre>

        <figure>
            <img src="element_snap_positions.png" alt="">

            <figcaption>
                The layout of the scroll container's contents in the example.
                The snap alignment container is represented by the red rectangle, and the snap margin 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 margin (represented by a yellow dotted line).
            </figcaption>
        </figure>
    </div>

    <div class="example">
        This example builds a paginated document that aligns each page near to (but not exactly on) the edge of the <a>scroll container</a>.
        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.

        <pre class="lang-css">
            .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;
            }
        </pre>

        <pre class="lang-html">
            &lt;div class="docScroller">
                &lt;div class="page">Page 1&lt;/div>
                &lt;div class="page">Page 2&lt;/div>
                &lt;div class="page">Page 3&lt;/div>
                &lt;div class="page">Page 4&lt;/div>
            &lt;/div>
        </pre>

        <figure>
            <img src="element_snap_positions_offset.png" alt="">

            <figcaption>
                The layout of the scroll container's contents in the example.
                The snap alignment container is represented by the red rectangle (inset from the top by 100px due to the scroll-snap-padding), and the snap margin is represented by the yellow rectangle.  Since the scroll-snap-align is "start" in the Y axis, a snap position is established at each scroll offset which aligns the Y-start of the snap alignment container (represented by a red dotted line) with the Y-start of a snap margin (represented by a yellow dotted line).
            </figcaption>
        </figure>
    </div>

Overview {#overview}
====================

    This module introduces control over <a>scroll snap positions</a>,
    which are scroll positions that produce particular alignments
    of content within a scrollable viewport.
    Using the 'scroll-snap-type' property on the relevant <a>scroll container</a>,
    the author can request a particular bias
    for the viewport to land on a valid <a>snap position</a>
    after scrolling operations.

    Valid <a>snap positions</a> can be specified
    as a particular alignment ('scroll-snap-align')
    of an element's <a>scroll snap margin</a> ('scroll-snap-margin', defaulting to its margin box)
    within the <a>scroll container</a>’s <a>snap alignment container</a>
    (the rectangle obtained by reducing its visual viewport by its 'scroll-snap-padding').
    This is conceptually equivalent to specifying the alignment of
    an <a>alignment subject</a> within an <a>alignment container</a>.
    A scroll position that satisfies the specified alignment
    is a valid <a>snap position</a>.

    <a>Snap positions</a> must only affect the nearest ancestor
    (on the element's <a>containing block chain</a>)
    <a>scroll container</a>.

Definitions {#definitions}
==========================

    <dl>
        <dt><dfn export>scroll container</dfn>
        <dd>
            An element which provides a scrolling user interface as described in [[!CSS21]], particularly in the section on overflow.

        <dt><dfn export>snap alignment container</dfn>
        <dd>
            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?

        <dt><dfn lt="scroll snap margin" local-lt="snap margin" export>snap margin</dfn>
        <dd>
            An element's snap margin is the rectangle obtained by expanding its border box by its 'scroll-snap-margin'.

        <dt><dfn lt="scroll snap position" local-lt="snap position" export>snap position</dfn>
        <dd>
            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.
    </dl>

Properties on the scroll container {#properties-on-the-scroll-container}
========================================================================

Scroll Snap Types: the 'scroll-snap-type' property {#scroll-snap-type}
----------------------------------------------------------------------

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

    Issue: <a href="https://lists.w3.org/Archives/Public/www-style/2015Nov/0328.html">Open issue</a> on whether to enhance the scroll-snap-type property for specifying the axis or adding a second property.  We have <a href="https://lists.w3.org/Archives/Public/www-style/2015Dec/0048.html">resolved</a> that this functionality be added once the issue is resolved.

    Issue: Currently considering renaming the values

    <pre class="propdef">
    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
    </pre>

    <dl dfn-type="value" dfn-for="scroll-snap-type">
        <dt><dfn>none</dfn>
        <dd>
            The visual viewport of this <a>scroll container</a> must ignore snap positions.

        <dt><dfn>mandatory</dfn>
        <dd>
            The visual viewport of this <a>scroll container</a> 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.

        <dt><dfn>proximity</dfn>
        <dd>
            The visual viewport of this <a>scroll container</a> 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.
    </dl>

Scroll Snap Padding: the 'scroll-snap-padding' property {#scroll-snap-padding}
------------------------------------------------------------------------------

    The 'scroll-snap-padding' property defines the <a>snap alignment container</a>, a region inset from the visual viewport of a <a>scroll container</a> used in calculating its <a>snap positions</a>.  The snap alignment container is used as the alignment container when calculating valid <a>snap positions</a>.

    <pre class="propdef">
    Name: scroll-snap-padding
    Value: [ <<length>> | <<percentage>> ]{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
    </pre>

    <dl dfn-type="value" dfn-for="scroll-snap-padding">
        <dt><dfn>[ <<length>> | <<percentage>> ]{1,4}</dfn>
        <dd>
            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.
    </dl>

    This property is a shorthand property that sets all of the 'scroll-snap-padding-*' longhands in one declaration.

Properties on the elements {#properties-on-the-elements}
========================================================

Scroll Snap Margin: the 'scroll-snap-margin' property {#scroll-snap-margin}
---------------------------------------------------------------------------

    The 'scroll-snap-margin' property defines the <a>scroll snap margin</a> on elements within a <a>scroll container</a>, used in calculating <a>snap positions</a> for that scroll container.

    <pre class="propdef">
    Name: scroll-snap-margin
    Value: <<length>>{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
    </pre>

    <dl dfn-type="value" dfn-for="scroll-snap-margin">
        <dt><dfn><<length>>{1,4}</dfn>
        <dd>
            Specifies the outset of the element's snap margin from the axis-aligned bounding box of the transformed border box, in the <a>scroll container's</a> coordinate space.  Outsets are applied to this bounding box, not the border box.

            Note: This ensures that the <a>scroll snap margin</a> is always rectangular and axis-aligned to the <a>scroll container's</a> coordinate space.
    </dl>

    This property is a shorthand property that sets all of the 'scroll-snap-margin-*' longhands in one declaration.

Scroll Snap Alignment: the 'scroll-snap-align' property {#scroll-snap-align}
----------------------------------------------------------------------------

    The 'scroll-snap-align' property specifies how an element's scroll snap margin should align with its ancestor scroll container's snap alignment container.  The two values specify the snapping behavior in the x and y axes, respectively.  If only one value is specified, the second value defaults to the same value.

    Issue: Should this be x/y axes, or inline/block?  Starting with x/y axes for consistency with padding/area, otherwise a writing mode change would result in a axis mismatch (since padding is physical by default).

    <pre class="propdef">
    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
    </pre>

    <dl dfn-type="value" dfn-for="scroll-snap-align">
        <dt><dfn>none</dfn>
        <dd>
            This box does not define a <a>snap position</a> in the specified axis.

        <dt><dfn>start</dfn>
        <dd>
            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 <a>snap position</a> in that axis.

        <dt><dfn>end</dfn>
        <dd>
            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 <a>snap position</a> in that axis.

        <dt><dfn>center</dfn>
        <dd>
            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 <a>snap position</a> in that axis.
    </dl>

Acknowledgements {#acknowledgements}
====================================

    Many thanks to lots of people for their proposals and recommendations, some of which are incorporated into this document.