Skip to content

Add scrollIntoView action #1964

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
hbenl wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add scrollIntoView action #1964

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
227 changes: 199 additions & 28 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4496,27 +4496,45 @@ <h2>Elements</h2>
or if it is not <a>connected</a>.

<p>To <dfn data-lt="scrolls into view|scrolled into view">scroll into view</dfn>
an <var><a>element</a></var>
perform the following steps
only if the element is not already <a>in view</a>:
a <var><a>node</a></var>
given optional arguments <var>onlyIfNecessary</var> (default true),
<var>behavior</var> (default "<code>instant</code>"),
<var>block</var> (default "<code>end</code>")
and <var>inline</var> (default "<code>nearest</code>"):
Comment thread
whimboo marked this conversation as resolved.
Resolved

<ol>
<li><p>Let <var>options</var> be
the following <a><code>ScrollIntoViewOptions</code></a>:
<li><p>Let <var>target</var> be determined as follows:

<dl>
<dt>"<code>behavior</code>"
<dd>"<code>instant</code>"
<dl class=switch>
<dt><var>node</var> implements {{Element}}
and has an associated [=CSS/box=]
<dd>
<ol>
<li><p>Let <var>target</var> be <var>node</var>.

<li><p>If <var>onlyIfNecessary</var> is true
and <var>target</var> is <a>in view</a>, return.
</ol>

<dt><a>Logical scroll position "<code>block</code>"</a>
<dd>"<code>end</code>"
<dt>Otherwise
<dd>
<ol>
<li><p>Let <var>target</var> be a new {{Range}} obtained by calling
{{Document/createRange()}} on <var>node</var>&apos;s [=Node/node document=]
and then invoking {{Range/selectNodeContents()}} on it with <var>node</var>
as argument.

<dt><a>Logical scroll position "<code>inline</code>"</a>
<dd>"<code>nearest</code>"
<li><p>If <var>onlyIfNecessary</var> is true
and the <var>target</var> <a>range is in view</a>, return.
</ol>
</dl>

<li><p>Run <a>Function.[[\Call]]</a>(<a>scrollIntoView</a>, <var>options</var>)
with <var>element</var> as the this value.
<li><p>Let <var>promise</var> be the result of <a data-lt="scroll target into view">scroll into view</a> <var>target</var>
with scroll behavior <var>behavior</var>,
block flow direction position <var>block</var>,
and inline base direction position <var>inline</var>.

<li><p>Return <var>promise</var>.
</ol>

<p><dfn>Editable</dfn> <a>elements</a>
Expand Down Expand Up @@ -4716,6 +4734,46 @@ <h3>Interactability</h3>
<li><p>Return the <a>elements from point</a>
given the coordinates <var>center point</var>.
</ol>

<p>A <dfn>{{Range}} is in view</dfn>
if the first {{DOMRect}}
returned by calling {{Range/getClientRects()}} on it
overlaps the <a>viewport</a>.
It can be checked this way:

<ol>
<li><p>Let <var>rectangles</var> be
the {{DOMRect}} sequence
returned by calling {{Range/getClientRects()}} on the {{Range}}.

<li><p>If <var>rectangles</var> has the length of 0, return false.

<li><p>Let <var>rectangle</var> be the first object in <var>rectangles</var>.

<li><p>Return true if all of the following conditions are true,
and false otherwise:
<ul>
<li><p><a>min</a>(<var>rectangle</var>&apos;s <a>x coordinate</a>,
<var>rectangle</var>&apos;s <a>x coordinate</a>
+ <var>rectangle</var>&apos;s <a>width dimension</a>)
is less than <a>innerWidth</a>.

<li><p><a>max</a>(<var>rectangle</var>&apos;s <a>x coordinate</a>,
<var>rectangle</var>&apos;s <a>x coordinate</a>
+ <var>rectangle</var>&apos;s <a>width dimension</a>)
is greater than 0.

<li><p><a>min</a>(<var>rectangle</var>&apos;s <a>y coordinate</a>,
<var>rectangle</var>&apos;s <a>y coordinate</a>
+ <var>rectangle</var>&apos;s <a>height dimension</a>)
is less than <a>innerHeight</a>.

<li><p><a>max</a>(<var>rectangle</var>&apos;s <a>y coordinate</a>,
<var>rectangle</var>&apos;s <a>y coordinate</a>
+ <var>rectangle</var>&apos;s <a>height dimension</a>)
is greater than 0.
</ul>
</ol>
</section> <!-- /Interactability -->

<section>
Expand Down Expand Up @@ -7895,6 +7953,10 @@ <h4>Null input source</h4>
a <a>tick</a>, or as a placeholder to indicate that an <a>input
source</a> does nothing during a particular <a>tick</a>.</td>
</tr>
<tr>
<td><dfn class="lint-ignore">scrollIntoView</dfn></td>
<td>Used to scroll a particular node into the viewport.</td>
</tr>
</table>

<p>To <dfn>create a null input source</dfn>, return a new <a>null input
Expand Down Expand Up @@ -8507,8 +8569,8 @@ <h3>Processing actions</h3>

<li><p>If <var>type</var> is "<code>none</code>"
let <var>action</var> be the result of <a>trying</a> to <a>process
a null action</a> with parameters <var>id</var>, and
<var>action item</var>.
a null action</a> with parameters <var>id</var>,
<var>action item</var>, and <var>actions options</var>.

<li><p>Otherwise, if <var>type</var> is "<code>key</code>"
let <var>action</var> be the result of <a>trying</a> to <a>process
Expand Down Expand Up @@ -8583,15 +8645,17 @@ <h3>Processing actions</h3>

<p>
To <dfn>process a null action</dfn> given
<var>id</var> and <var>action item</var>:
<var>id</var>, <var>action item</var>, and <var>actions options</var>:

<ol class="algorithm">
<li><p>
Let <var>subtype</var> be the result of <a>getting a property</a>
named "<code>type</code>" from <var>action item</var>.

<li><p>
If <var>subtype</var> is not "<code>pause</code>",
If <var>subtype</var> is not one of the values
"<code>pause</code>"
or "<code>scrollIntoView</code>",
return <a>error</a> with <a>error code</a> <a>invalid argument</a>.

<li><p>
Expand All @@ -8601,12 +8665,15 @@ <h3>Processing actions</h3>
and <var>subtype</var>.

<li><p>
Let <var>result</var> be the result
of <a>trying</a> to <a>process a pause action</a>
If <var>subtype</var> is "<code>pause</code>",
return the result of <a>trying</a> to <a>process a pause action</a>
with arguments <var>action item</var> and <var>action</var>.

<li><p>
Return <var>result</var>.
If <var>subtype</var> is "<code>scrollIntoView</code>",
return the result of <a>trying</a> to <a>process a scrollIntoView action</a>
with arguments <var>action item</var>, <var>action</var>,
and <var>actions options</var>.
</ol>

<p>
Expand Down Expand Up @@ -8833,6 +8900,76 @@ <h3>Processing actions</h3>
<li><p>Return success with data <var>action</var>.
</ol>

<p>To <dfn>process a scrollIntoView action</dfn> given <var>action item</var>,
<var>action</var>, and <var>actions options</var>:</p>

<ol class="algorithm">
<li><p>Let <var>node</var> be the result of <a>getting the property</a>

@whimboo whimboo Aug 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some lines up we use getting a property. What shall we use?

@hbenl hbenl Sep 2, 2026

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both getting the property and getting a property are used throughout the spec.

@whimboo whimboo Sep 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mind then filing a new issue so that we can get this cleaned-up?

"<code>node</code>" from <var>action item</var>.

<li><p>If <var>actions options</var>&apos; <a>is element origin</a> steps
given <var>node</var> return false, return <a>error</a> with
<a>error code</a> <a>invalid argument</a>.

<li><p>Set the <code>node</code> property of <var>action</var>
to <var>node</var>.

<li><p>Let <var>onlyIfNecessary</var> be the result of <a>getting the
property</a> "<code>onlyIfNecessary</code>" from <var>action item</var>.

<li><p>If <var>onlyIfNecessary</var> is <a>undefined</a>, let
<var>onlyIfNecessary</var> be true.

<li><p>If <var>onlyIfNecessary</var> is not a <a>boolean</a>, return
<a>error</a> with <a>error code</a> <a>invalid argument</a>.

<li><p>Set the <code>onlyIfNecessary</code> property of <var>action</var>
to <var>onlyIfNecessary</var>.

<li><p>Let <var>behavior</var> be the result of <a>getting the property</a>
"<code>behavior</code>" from <var>action item</var>.

<li><p>If <var>behavior</var> is <a>undefined</a>, let
<var>behavior</var> be "<code>instant</code>".

<li><p>If <var>behavior</var> is not one of the values
"<code>auto</code>", "<code>instant</code>" or "<code>smooth</code>", return <a>error</a>
with <a>error code</a> <a>invalid argument</a>.

<li><p>Set the <code>behavior</code> property of <var>action</var>
to <var>behavior</var>.

<li><p>Let <var>block</var> be the result of <a>getting the property</a>
"<code>block</code>" from <var>action item</var>.

<li><p>If <var>block</var> is <a>undefined</a>, let
<var>block</var> be "<code>end</code>".

<li><p>If <var>block</var> is not one of the values
"<code>start</code>", "<code>center</code>", "<code>end</code>",
or "<code>nearest</code>", return <a>error</a> with
<a>error code</a> <a>invalid argument</a>.

<li><p>Set the <code>block</code> property of <var>action</var>
to <var>block</var>.

<li><p>Let <var>inline</var> be the result of <a>getting the property</a>
"<code>inline</code>" from <var>action item</var>.

<li><p>If <var>inline</var> is <a>undefined</a>, let
<var>inline</var> be "<code>nearest</code>".

<li><p>If <var>inline</var> is not one of the values
"<code>start</code>", "<code>center</code>", "<code>end</code>",
or "<code>nearest</code>", return <a>error</a> with
<a>error code</a> <a>invalid argument</a>.

<li><p>Set the <code>inline</code> property of <var>action</var>
to <var>inline</var>.

<li><p>Return success with data <var>action</var>.
</ol>

<p>To <dfn>process a pointer up or pointer down action</dfn>
given <var>action item</var>, and <var>action</var>:</p>

Expand Down Expand Up @@ -9266,6 +9403,7 @@ <h3>Dispatching actions</h3>
<table class=simple>
<tr><th>source type <th>subtype <th>Dispatch action algorithm
<tr><td>"<code>none</code>" <td>"<code>pause</code>" <td><a>Dispatch a pause action</a>
<tr><td>"<code>none</code>" <td>"<code>scrollIntoView</code>" <td><a>Dispatch a scrollIntoView action</a>
<tr><td>"<code>key</code>" <td>"<code>pause</code>" <td><a>Dispatch a pause action</a>
<tr><td>"<code>key</code>" <td>"<code>keyDown</code>" <td><a>Dispatch a keyDown action</a>
<tr><td>"<code>key</code>" <td>"<code>keyUp</code>" <td><a>Dispatch a keyUp action</a>
Expand Down Expand Up @@ -9330,6 +9468,41 @@ <h4>General actions</h4>
<ol class="algorithm">
<li><p>Return <a>success</a> with data <a><code>null</code></a>.
</ol>

<p>To <dfn>dispatch a scrollIntoView action</dfn> given <var>action
object</var>, <var>source</var>, <var>global key state</var>,
<var>tick duration</var>, <var>browsing context</var>,
and <var>actions options</var>:

<ol class="algorithm">
<li><p>Let <var>node</var> be the result of <a>trying</a> to run
<var>actions options</var>&apos; <a>get element origin</a> steps with
the <code>node</code> property of <var>action object</var>
and <var>browsing context</var>.

<li><p>If <var>node</var> is null, return <a>error</a> with
<a>error code</a> <a>no such element</a>.

<li><p>Let <var>onlyIfNecessary</var> be the <code>onlyIfNecessary</code>
property of <var>action object</var>.

<li><p>Let <var>behavior</var> be the <code>behavior</code>
property of <var>action object</var>.

<li><p>Let <var>block</var> be the <code>block</code>
property of <var>action object</var>.

<li><p>Let <var>inline</var> be the <code>inline</code>
property of <var>action object</var>.

<li><p>Let <var>promise</var> be the result of <a>scroll into view</a> <var>node</var> with
<var>onlyIfNecessary</var>, <var>behavior</var>, <var>block</var>,
and <var>inline</var>.

<li><p><a>Asynchronously wait</a> for <var>promise</var> to resolve.

<li><p>Return <a>success</a> with data <a><code>null</code></a>.
</ol>
</section> <!-- /General actions -->


Expand Down Expand Up @@ -11932,10 +12105,11 @@ <h2>Index</h2>
sometimes here referred to as the <i>viewport</i>.
</ul>

<dd>The following properties are defined in
the CSS Display Module Level 3 specification: [[CSS3-DISPLAY]]
<dd>The following terms are defined in
the CSS Display Module Level 4 specification: [[CSS-DISPLAY-4]]
<ul>
<!-- Display property --> <li>The <dfn><a href=https://drafts.csswg.org/css-display/#the-display-properties><code>display</code></a></dfn> property
<!-- Display property --> <li>The <dfn><a href=https://drafts.csswg.org/css-display-4/#the-display-properties><code>display</code></a></dfn> property
<!-- Box --> <li><dfn><a href=https://drafts.csswg.org/css-display-4/#box><code>box</code></a></dfn>
</ul>

<dd>The following terms are defined in
Expand Down Expand Up @@ -11972,10 +12146,7 @@ <h2>Index</h2>
<!-- screenY --> <li><dfn><a href=https://drafts.csswg.org/cssom-view/#dom-window-screeny>screenY</a></dfn>
<!-- scrollX --> <li><dfn><a href="https://drafts.csswg.org/cssom-view/#dom-window-scrollx">scrollX</a></dfn>
<!-- scrollY --> <li><dfn><a href="https://drafts.csswg.org/cssom-view/#dom-window-scrolly">scrollY</a></dfn>
<!-- scrollIntoView --> <li><dfn><a href=https://drafts.csswg.org/cssom-view/#dom-element-scrollintoview>scrollIntoView</a></dfn>
<!-- ScrollIntoViewOptions --> <li><dfn><a href=https://drafts.csswg.org/cssom-view/#dictdef-scrollintoviewoptions><code>ScrollIntoViewOptions</code></a></dfn>
<!-- ScrollIntoViewOptions block --> <li><dfn><a href=https://drafts.csswg.org/cssom-view/#dom-scrollintoviewoptions-block>Logical scroll position "<code>block</code>"</a></dfn>
<!-- ScrollIntoViewOptions inline --> <li><dfn><a href=https://drafts.csswg.org/cssom-view/#dom-scrollintoviewoptions-inline>Logical scroll position "<code>inline</code>"</a></dfn>
<!-- scroll target into view --> <li><dfn><a href=https://drafts.csswg.org/cssom-view/#scroll-a-target-into-view>scroll target into view</a></dfn>
<!-- visual viewport --> <li><dfn><a href="https://drafts.csswg.org/cssom-view/#visual-viewport">visual viewport</a></dfn>
</ul>

Expand Down
Loading