Skip to content

Add scrollIntoView action - #1964

Open
hbenl wants to merge 1 commit into
w3c:masterfrom
hbenl:scrollintoview
Open

Add scrollIntoView action#1964
hbenl wants to merge 1 commit into
w3c:masterfrom
hbenl:scrollintoview

Conversation

@hbenl

@hbenl hbenl commented May 27, 2026

Copy link
Copy Markdown

This PR adds scrollIntoView to the general actions.
The action should also be able to scroll text nodes (which can be passed in from WebDriver BiDi) and elements with display: contents into view. To this end, the "scroll into view" steps are updated to create a Range object for such nodes and call the "Scroll target into view" steps in the CSSOM View spec (which support Ranges) directly.
Note that this is a breaking change for interaction commands that implicitly scroll an element into view: previously, the implicit attempt to scroll an element with display: contents into view would do nothing but now it will be scrolled into view.

Fixes #1005.


This change is Reviewable


Preview | Diff

@hbenl
hbenl marked this pull request as ready for review June 1, 2026 13:50

@whimboo whimboo left a comment

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.

Thanks @hbenl. I did a first review pass for this proposed enhancement and I have a couple of comments. But I would also see feedback from @jgraham.

Comment thread index.html
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>"):

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.

Not sure if nearest would work as default. Usually we use the element's in-view center point for the interaction and scrolling only as little as possible most likely would still keep the majority of the element outside of the viewport. Should we maybe use end here as well similar to what we use for block?

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.

I wanted the scrollIntoView action defaults to match what WebDriver does for the interaction commands.

Comment thread index.html Outdated
<dt><a>Logical scroll position "<code>inline</code>"</a>
<dd>"<code>nearest</code>"
<li><p>If <var>onlyIfNecessary</var> is true
and <var>target</var> is <a data-lt="range is in view">in view</a>, return.

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.

This renders in view similarly to the above option and is confusing. We most likely want target's <a>range is in view</a> or similar.

Also here we only test the viewport overlapping for the first client rect (shouldn't we take all into account?).

Per AI it might cause issues with overflow: hidden when in view would return true but it's actually clipped by the container. So onlyIfNecessary would wrongly skip the scroll. If that's acceptable it might warrant at least a note. By lets see what @jgraham will think about it.

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.

I changed it to the <var>target</var> <a>range is in view</a> (not target's range because target itself is a range here).

Also here we only test the viewport overlapping for the first client rect (shouldn't we take all into account?).

Again I tried to match how scrolling into view is done for WebDriver interaction commands: the in view check uses the pointer-interactable paint tree which uses the element's in-view center point which is "the intersection between the element's first DOMRect of getClientRects() and the initial viewport" (but I was surprised by this logic as well).

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

<li><p><a>Scroll into view</a> <var>node</var> with

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.

If we have a scrolling behavior of auto or smooth the scrolling will be asynchronous. We should wait until the scrolling is done before continuing dispatching the remaining actions.

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.

I assumed this is already covered by waiting for "pending asynchronous waits arising from the last invocation of the dispatch tick actions steps" after dispatching an action because scroll a target into view returns a Promise that resolves when scrolling is done.
@jgraham did I understand this correctly?

Comment thread index.html Outdated

<li><p>Run <a>Function.[[\Call]]</a>(<a>scrollIntoView</a>, <var>options</var>)
with <var>element</var> as the this value.
<li><p><a>Scroll <var>target</var> into view</a>

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.

Is it ok to put a var inside an anchor?

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.

It's not ideal, so I changed it to <a>Scroll into view</a> <var>target</var>.

Comment thread index.html
<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>

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?

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 requested a review from jgraham August 25, 2026 15:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Missing "scroll into view" Actions primitive

2 participants