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, Apple, 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 programmatically. 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 ]{1,2}

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

SnapEvents

			[Exposed=Window]
			interface SnapEvent : Event {
				constructor(DOMString type, optional SnapEventInit eventInitDict = {});
				readonly attribute EventTarget? target;
				readonly attribute SnapTargetList snappedTargets;
				readonly attribute SnapTargetList snapTargets;
				readonly attribute boolean invokedProgrammatically;
				readonly attribute boolean smoothlyScrolled;
			};

			[Exposed=Window]
			interface SnapTargetList {
			    readonly attribute SnapTargetArray x;
			    readonly attribute SnapTargetArray y;
			};

			[Exposed=Window]
			interface SnapTargetArray {
			    readonly attribute unsigned long length;
			    getter EventTarget? item (unsigned long index);
			};

			dictionary SnapEventInit : EventModifierInit {
			    sequence<EventTarget> snappedTargetsX = [];
			    sequence<EventTarget> snappedTargetsY = [];
			    sequence<EventTarget> snapTargetsListX = [];
			    sequence<EventTarget> snapTargetsListY = [];
			};

SnapEvent . target: This is the scroll container of the snapped-to element.
SnapEvent . snappedTargets: An object with 2 keys for each axis, each key returns an array of snapped targets.
SnapEvent . snapTargets: An object with 2 keys for each axis, each key returns an array of the aggregated snap children.
SnapEvent . invokedProgrammatically: A boolean informing developers if a user or script invoked scroll that caused snapChanged.
SnapEvent . smoothlyScrolled: A boolean informing developers if the snap change was instant or interpolated.

snapChanged

The event is dispatched when a new snap target has been snapped to, providing what caused it. It should be dispatched: * if user scroll interaction has ended and a new item has been rested on. If a user is still touching the screen or the touchpad, this event should not fire, even if the scroll position is exactly at a snapped element's position. * if animations or transitions change the snapped style of the container or children, IF they have in fact changed the snap target.

Type	`snapChanged`
Interface	{{SnapEvent}}
Sync / Async	Async
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	No
Composed	Yes
Default action	None
Context (trusted events)	{{Event}}.{{Event/target}} : scroll container of the snapped-to element {{SnapEvent}}.{{snappedTargets}} : an object with 2 keys for each axis, each key returns an array of snapped targets {{SnapEvent}}.{{snapTargets}} : an object with 2 keys for each axis, each key returns an array of the aggregated snap children {{SnapEvent}}.{{invokedProgrammatically}} : a boolean informing developers if a user or script invoked scroll that caused snapChanged {{SnapEvent}}.{{smoothlyScrolled}} : a boolean informing developers if the snap change was instant or interpolated

snapChanging

Should fire every time, and as soon as, the UA has determined a new snap child until the new child is snapped to.

Type	`snapChanging`
Interface	{{SnapEvent}}
Sync / Async	Async
Bubbles	Yes
Trusted Targets	`Element`
Cancelable	No
Composed	Yes
Default action	None
Context (trusted events)	{{Event}}.{{Event/target}} : scroll container of the snapped-to element. {{SnapEvent}}.{{snappedTargets}} {{SnapEvent}}.{{snapTargets}} : an object with 2 keys for each axis, each key returns an array of the aggregated snap children. {{SnapEvent}}.{{invokedProgrammatically}} : a boolean informing developers if a user or script invoked scroll that caused snapChanged. {{SnapEvent}}.{{smoothlyScrolled}} : a boolean informing developers if the snap change was instant or interpolated.

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
	Logical property group: scroll-start
	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
	Logical property group: scroll-start
	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-target' {#scroll-start-target-longhands-logical} --------------------------------------------------------------------------

	Name: scroll-start-target-block, scroll-start-target-inline
	Value: auto | none
	Initial: none
	Applies to: all elements
	Inherited: no
	Logical property group: scroll-start-target
	Percentages: n/a
	Computed Value: either of the keywords "none" or "auto"
	Animation type: not animatable

... Physical Longhands for 'scroll-start-target' {#scroll-start-target-longhands-physical} ----------------------------------------------------------------------

	Name: scroll-start-target-x, scroll-start-target-y
	Value: none | auto
	Initial: none
	Applies to: all elements
	Inherited: no
	Logical property group: scroll-start-target
	Percentages: n/a
	Computed value: either of the keywords "none" or "auto"
	Animation type: not animatable

...