Overview.bs

<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 x or y position,
	both users, page authors and browsers benefit.

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


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

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

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

	<pre class="propdef">
	Name: scroll-start
	Value: auto | [end | center] | <<length-percentage>>
	Initial: none
	Applies to: all elements
	Inherited: no
	Percentages: n/a
	Computed value: specified keyword(s)
	Animation type: discrete
	</pre>

This property is a shorthand property that sets all of the scroll-start-* longhands in one declaration. It does not work like 'margin', where a value is repeated to all sides. {{scroll-start: 200px}} is not {{scroll-start: 200px 200px}}, it's {{scroll-start: 200px 0}}. Inline is first, followed by block.

Values are defined as follows:

	<dl dfn-type=value dfn-for="scroll-snap-type">
		<dt><dfn>end</dfn>
		<dd>
			Scroll position starts at the end of a <a>scroll container</a>.
			Property value is at risk, may be duplicative.

		<dt><dfn>center</dfn>
		<dd>
			Scroll position starts at the middle of a <a>scroll container</a>.
			Property value is at risk, may be duplicative.
	</dl>

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:

	<dl dfn-type=value dfn-for="scroll-snap-type">
		<dt><dfn>:snapped-x</dfn>
		<dd>
			Matches the child snapped on the {{x}} axis.

		<dt><dfn>:snapped-y</dfn>
		<dd>
			Matches the child snapped on the {{y}} 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>

Snap Events {#todo}
===================

<!--
████████ ██     ██ ████████ ██    ██ ████████  ██████
██       ██     ██ ██       ███   ██    ██    ██    ██
██       ██     ██ ██       ████  ██    ██    ██
██████   ██     ██ ██████   ██ ██ ██    ██     ██████
██        ██   ██  ██       ██  ████    ██          ██
██         ██ ██   ██       ██   ███    ██    ██    ██
████████    ███    ████████ ██    ██    ██     ██████
-->

'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>{{snapChanged}}
				<td>{{scroll!!event}}
			<tr>
				<th>{{snapChanging}}
				<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 | [end | center] | <<length-percentage>>
	Initial: auto
	Applies to: <a>scroll containers</a>
	Inherited: no
	Percentages: relative to 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>

	Negative values are invalid.

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

	<pre class="propdef">
	Name: scroll-start-inline, scroll-start-block
	Value: auto | [end | center] | <<length-percentage>>
	Initial: auto
	Applies to: <a>scroll containers</a>
	Inherited: no
	Percentages: relative to 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>

	Negative values are invalid.