Title: CSS Scroll Snap Module Level 2
Group: csswg
Shortname: css-scroll-snap
Level: 2
Status: ED
Implementation Report: https://wpt.fyi/results/css/css-scroll-snap
Work Status: Testing
ED: https://drafts.csswg.org/css-scroll-snap-2/
Editor: Matt Rakow, Microsoft, w3cid 62267
Editor: Jacob Rossi, Microsoft, w3cid 45616
Editor: Tab Atkins-Bittner, Google, http://xanthir.com/contact/, w3cid 42199
Editor: Elika J. Etemad / fantasai, Invited Expert, http://fantasai.inkedblade.net/contact, w3cid 35400
Editor: Adam Argyle, Google, https://nerdy.dev, w3cid 112669
Abstract: This module contains features to control panning and scrolling behavior with “snap positions”.
Status Text:
 A test suite and an implementation report will be produced during the
 CR period.

Introduction {#intro} ===================== 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. 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. Motivating Examples {#examples} ===============================

A carousel that starts in the middle:

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

A search bar is available when the user scrolls back to the top:

            .scrollport {
                overflow-block: auto;
            }

            main {
                scroll-start-target: auto;
            }

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

Setting Where Scroll Starts {#properties-on-the-scroll-container} ================================================================= The 'scroll-start' property {#scroll-start} -------------------------------------------

	Name: scroll-start
	Value: [ auto | start | end | center | left | right | top | bottom | <> ]{1,2}

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 ''scroll-start/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: ...
<>: ... 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.

Interaction with ''display: none'' and initial creation

Same behavior that animations follow with first layout.

Slow page loading or document streaming behavior

TODO TODO If the scrollport has a in-page '':target'' via a URL fragment or a previous scroll position, then ''scroll-start'' is unused. Existing target logic should go unchanged. This makes ''scroll-start'' a soft request in the scroll position resolution routines.

Interaction with ''place-content''

TODO Side note: While ''place-content'' can make a scroller appear to start in the center or end, no browser supports it and it appears complicated to resolve.

Interaction with "find in page"

TODO

Interaction ''scroll-snap'' containers

This effectively will layout and start scroll at the snapped child, thus negating / cancelling ''scroll-start''. ''scroll-start'' will only work if nothing else has effected the scroll position.

Nested scrollers with ''scroll-start''

Should follow patterns that scroll snap has set.

Interaction when ''display'' is toggled

Same behavior that animations follow with ''first layout''.

Interaction with RTL and LTR

Logical properties are offered for length offsets that should be flow relative. Furthermore, the ''end'' and ''start'' keywords are always logical. The 'scroll-start-target' property {#scroll-start-target} -------------------------------------------

  Name: scroll-start-target
  Value: [ none | auto ]

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.

Styling Snapped Items {#todo} ============================= The Snapped-element Pseudo-class: '':snapped'' {#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. Snap Events {#snap-events} =================== {{snapChanged}} and {{snapChanging}} {#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.

Event handler	Event handler event type
snapChanged	{{scroll!!event}}
snapChanging	{{scroll!!event}}

Appendix A: Longhands {#longhands} ================================== The physical and logical longhands (and their shorthands) interact as defined in [[!CSS-LOGICAL-1]]. Physical Longhands for 'scroll-start' {#scroll-start-longhands-physical} ----------------------------------------------------------------------

	Name: scroll-start-x, scroll-start-y
	Value: auto | start | end | center | <>
	Initial: auto
	Applies to: scroll containers
	Inherited: no
	Percentages: relative to the corresponding axis of the scroll container’s scrollport
	Computed value: the keyword ''scroll-start/auto'' or a computed <> value
	Animation type: by computed value type

... Flow-relative Longhands for 'scroll-start' {#scroll-start-longhands-logical} --------------------------------------------------------------------------

	Name: scroll-start-inline, scroll-start-block
	Value: auto | start | end | center | <>
	Initial: auto
	Applies to: scroll containers
	Inherited: no
	Percentages: relative to the corresponding axis of the scroll container’s scrollport
	Computed value: the keyword ''scroll-start/auto'' or a computed <> value
	Animation type: by computed value type

...