CSS Scroll Snap Module Level 2

1. Introduction

This section is not normative.

This is currently a draft spec over Scroll Snap 1.

Scroll experiences don’t always start at the beginning. Interactions with carousels, swipe controls, and listviews often start somewhere in the middle, and each require JavaScript to set this position on page load. By enabling CSS to specify this scroll start position, both users, page authors and browsers benefit.

In addition to setting an initial scroll position, developers need insights and events into Scroll Snap. Events like which element is snapped on which axis, when the snap event is changing, when snap completes and conveniences for snapping to children programatically.

1.1. First Layout

This event should follow the Animation code path. When animation objects are created and fire events, this is when a box has it’s first layout.

2. Motivating Examples

.carousel {
    overflow-inline: auto;
    scroll-start: center;
}

<div class="carousel">
    <img src="img1.jpg">
    <img src="img2.jpg">
    <img src="img3.jpg">
    <img src="img4.jpg">
    <img src="img5.jpg">
</div>

.scrollport {
    overflow-block: auto;
}

main {
    scroll-start-target: auto;
}

<div class="scrollport">
    <nav>
        ...
    </nav>
    <main>
        ...
    </main>
</div>

3. Setting Where Scroll Starts

3.1. The scroll-start property

This property is a shorthand property that sets all of the scroll-start-* longhands in one declaration. The first value defines the scroll starting point in the block axis, the second sets it in the inline axis. If the second value is omitted, it defaults to start. If scroll-start-target is set on any child, scroll-start is not used, in favor of using the element as the offset.

Values are defined as follows:

auto

...

<length-percentage [0,∞]>

...

Negative values are invalid. Values corresponding to a length greater than the width/height of the scrollport are valid, but clamped to the width/height of the scrollport.

start

center

end

Equivalent to 0%, 50%, and 100%, respectively.

3.1.1. Interaction with display: none and initial creation

3.1.2. Slow page loading or document streaming behavior

3.1.3. Interaction with fragment navigation

3.1.4. Interaction with place-content

3.1.5. Interaction with "find in page"

3.1.6. Interaction scroll-snap containers

3.1.7. Nested scrollers with scroll-start

3.1.8. Interaction when display is toggled

3.1.9. Interaction with RTL and LTR

3.2. The scroll-start-target property

This property is a shorthand property that sets all of the scroll-start-target-* longhands in one declaration. The first value defines the scroll starting point in the block axis, the second sets it in the inline axis. If the second value is omitted, it defaults to none.

Values are defined as follows:

none

Element is not a scroll-start-target.

auto

Element is used to calculate the scroll-start position, taking into account scroll-padding or scroll-margin , same as a scroll-snap target.

4. Styling Snapped Items

4.1. The Snapped-element Pseudo-class: :snapped

The :snapped pseudo-class matches any scroll snap targets, regardless of axis. The longform physical and logical pseudo-class selectors allow for more finite snapped children styling as they can target an individual axis.

More specific options are defined as follows:

:snapped-x

Matches the child snapped on the horizontal axis.

:snapped-y

Matches the child snapped on the vertical axis.

:snapped-inline

Matches the child snapped on the inline axis.

:snapped-block

Matches the child snapped on the block axis.

Note: Issue #6985
Need to figure out resolution of the initial frame.

5. Snap Events

5.1. snapChanged and snapChanging

CSS scroll snap points are often used as a mechanism to create scroll interactive "selection" components, where selection is determined with JavaScript intersection observers and a scroll end guestimate. By creating a built-in event, the invisible state will become actionable, at the right time, and always correct.

Appendix A: Longhands

The physical and logical longhands (and their shorthands) interact as defined in [CSS-LOGICAL-1].

Physical Longhands for scroll-start

...

Flow-relative Longhands for scroll-start

...