<pre class='metadata'>

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.

</pre>

Introduction {#intro}

=====================

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

<em>This is currently a draft spec over Scroll Snap 1.</em>

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}

===============================

<div class="example">

A carousel that starts in the middle:

<pre class="lang-css">

.carousel {

overflow-inline: auto;

scroll-start: center;

}

</pre>

<pre class="lang-html">

&lt;div class="carousel">

&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="images/element_snap_positions.png" alt="">

<figcaption>

The layout of the scroll container’s contents in the example.

The snapport is represented by the red rectangle, and the snap area is represented by the yellow rectangle. Since the scroll-snap-align is “center” in the inline (horizontal) axis, a snap position is established at each scroll position which aligns the X-center of the snapport (represented by a red dotted line) with the X-center of a snap area (represented by a yellow dotted line).

</figcaption>

</figure> -->

</div>

<div class="example">

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

<pre class="lang-css">

.scrollport {

overflow-block: auto;

}

main {

scroll-start-target: auto;

}

</pre>

<pre class="lang-html">

&lt;div class="scrollport">

&lt;nav>

...

&lt;/nav>

&lt;main>

...

&lt;/main>

&lt;/div>

</pre>

<!-- <figure>

<img src="images/element_snap_positions.png" alt="">

<figcaption>

The layout of the scroll container’s contents in the example.

The snapport is represented by the red rectangle, and the snap area is represented by the yellow rectangle. Since the scroll-snap-align is “center” in the inline (horizontal) axis, a snap position is established at each scroll position which aligns the X-center of the snapport (represented by a red dotted line) with the X-center of a snap area (represented by a yellow dotted line).

</figcaption>

</figure> -->

</div>

Setting Where Scroll Starts {#properties-on-the-scroll-container}

=================================================================

<!-- BIG TEXT: SCROLL START -->

The 'scroll-start' property {#scroll-start}

-------------------------------------------

<pre class="propdef shorthand">

Name: scroll-start

Value: [ auto | start | end | center | left | right | top | bottom | <<length-percentage [0,∞]>> ]{1,2}

</pre>

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:

<dl dfn-type=value dfn-for="scroll-start, scroll-start-x, scroll-start-y, scroll-start-block, scroll-start-inline">

<dt><dfn>auto</dfn>

<dd>

...

<dt><dfn><<length-percentage [0,∞]>></dfn>

<dd>

...

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.

<dt><dfn>start</dfn>

<dt><dfn>center</dfn>

<dt><dfn>end</dfn>

<dd>

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

</dl>

<h4 id="display-none-behavior">Interaction with ''display: none'' and initial creation</h4>

Same behavior that animations follow with <a href="#first-layout">first layout</a>.

<h4 id="slow-page-load-behavior">Slow page loading or document streaming behavior</h4>

TODO

<h4 id="fragment-navigation-behavior">Interaction with ''fragment navigation''</h4>

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.

<h4 id="place-content-behavior">Interaction with ''place-content''</h4>

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.

<h4 id="find-in-page-behavior">Interaction with "find in page"</h4>

TODO

<h4 id="scroll-snap-container-behavior">Interaction ''scroll-snap'' containers</h4>

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.

<h4 id="nested-scrollers">Nested scrollers with ''scroll-start''</h4>

Should follow patterns that scroll snap has set.

<h4 id="toggling-display-none">Interaction when ''display'' is toggled</h4>

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

<h4 id="rtl">Interaction with RTL and LTR</h4>

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}

-------------------------------------------

<pre class="propdef shorthand">

Name: scroll-start-target

Value: [ none | auto ]

</pre>

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:

<dl dfn-type=value dfn-for="scroll-start-target, scroll-start-target-x, scroll-start-target-y, scroll-start-target-block, scroll-start-target-inline">

<dt><dfn>none</dfn>

<dd>Element is not a ''scroll-start-target''.

<dt><dfn>auto</dfn>

<dd>Element is used to calculate the ''scroll-start'' position,

taking into account ''scroll-padding'' or ''scroll-margin'' ,

same as a ''scroll-snap'' target.

</dl>

Styling Snapped Items {#todo}

=============================

The Snapped-element Pseudo-class: '':snapped'' {#snapped}

-------------------------------------------------------

The <dfn selector>:snapped</dfn> 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:

<dl dfn-type=selector>

<dt><dfn>:snapped-x</dfn>

<dd>

Matches the child snapped on the horizontal axis.

<dt><dfn>:snapped-y</dfn>

<dd>

Matches the child snapped on the vertical axis.

<dt><dfn>:snapped-inline</dfn>

<dd>

Matches the child snapped on the [=inline=] axis.

<dt><dfn>:snapped-block</dfn>

<dd>

Matches the child snapped on the [=block=] axis.

</dl>

Note: <a href="https://github.com/w3c/csswg-drafts/issues/6985#issuecomment-1049036401">Issue #6985</a><br>

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.

<table class="data" id="eventhandlers">

<thead>

<tr>

<th>Event handler

<th>Event handler event type

<tbody>

<tr>

<th><dfn event>snapChanged</dfn>

<td>{{scroll!!event}}

<tr>

<th><dfn event>snapChanging</dfn>

<td>{{scroll!!event}}

</table>

<!--

██ ███████ ██ ██ ██████ ██ ██ ███ ██ ██ ████████ ██████

██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██ ██

██ ██ ██ ████ ██ ██ ██ ██ ██ ██ ████ ██ ██ ██ ██

██ ██ ██ ██ ██ ██ ██ ████ █████████ ██ ██ ██ ██ ██ ██ ██ ██████

██ ██ ██ ██ ████ ██ ██ ██ ██ █████████ ██ ████ ██ ██ ██

██ ██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ██ ███ ██ ██ ██ ██

████████ ███████ ██ ██ ██████ ██ ██ ██ ██ ██ ██ ████████ ██████

-->

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}

----------------------------------------------------------------------

<pre class="propdef">

Name: scroll-start-x, scroll-start-y

Value: auto | start | end | center | <<length-percentage [0,∞]>>

Initial: auto

Applies to: <a>scroll containers</a>

Inherited: no

Percentages: relative to the corresponding axis of the scroll container’s scrollport

Computed value: the keyword ''scroll-start/auto'' or a computed <<length-percentage>> value

Animation type: by computed value type

</pre>

...

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

--------------------------------------------------------------------------

<pre class="propdef">

Name: scroll-start-inline, scroll-start-block

Value: auto | start | end | center | <<length-percentage [0,∞]>>

Initial: auto

Applies to: <a>scroll containers</a>

Inherited: no

Percentages: relative to the corresponding axis of the scroll container’s scrollport

Computed value: the keyword ''scroll-start/auto'' or a computed <<length-percentage>> value

Animation type: by computed value type

</pre>

...