CSSOM View Module Level 1

1. Background

Many of the features defined in this specification have been supported by browsers for a long period of time. The goal of this specification is to define these features in such a way that they can be implemented by all browsers in an interoperable manner. The specification also defines a some new features which allow for scroll customization.

2. Terminology

Terminology used in this specification is from DOM, CSSOM and HTML. [DOM] [CSSOM] [HTML]

An element body (which will be the body element) is potentially scrollable in an axis if all of the following conditions are true:

• body has an associated box.

• body’s parent element’s computed value of the overflow-x or overflow-y properties (whichever is in the given axis) is neither visible nor clip.

• body’s computed value of the overflow-x or overflow-y properties (whichever is in the given axis) is neither visible nor clip.

Note: A body element that is potentially scrollable might not have a scrolling box. For instance, it could have a used value of overflow being auto but not have its content overflowing its content area.

A scrolling box of a viewport or element has two overflow directions, which are the block-end and inline-end directions for that viewport or element. Note that the initial scroll position might not be aligned with the scrolling area origin depending on the content-distribution properties, see CSS Box Alignment 3 § 5.3 Alignment Overflow and Scroll Containers.

The term scrolling area refers to a box of a viewport or an element that has the following edges, depending on the viewport’s or element’s scrolling box’s overflow directions.

The origin of a scrolling area is the origin of the initial containing block if the scrolling area is a viewport, and otherwise the top left padding edge of the element when the element has its default scroll position. The x-coordinate increases rightwards, and the y-coordinate increases downwards.

The beginning edges of a particular set of edges of a box or element are the following edges:

If the overflow directions are rightward and downward

The top and left edges.

If the overflow directions are leftward and downward

The top and right edges.

If the overflow directions are leftward and upward

The bottom and right edges.

If the overflow directions are rightward and upward

The bottom and left edges.

The ending edges of a particular set of edges of a box or element are the following edges:

If the overflow directions are rightward and downward

The bottom and right edges.

If the overflow directions are leftward and downward

The bottom and left edges.

If the overflow directions are leftward and upward

The top and left edges.

If the overflow directions are rightward and upward

The top and right edges.

The visual viewport is a kind of viewport whose scrolling area is another viewport, called the layout viewport.

In addition to scrolling, the visual viewport may also apply a scale transform to its layout viewport. This transform is applied to the canvas of the layout viewport and does not affect its internal coordinate space.

Note: The scale transform of the visual viewport is often referred to as "pinch-zoom". Conceptually, this transform changes the size of the CSS reference pixel but changes the size of the layout viewport proportionally so that it does not cause reflow of the page’s contents.

The magnitude of the scale transform is known as the visual viewport’s scale factor.

The VisualViewport object has an associated document, which is a Document object. It is the associated document of the owner Window of VisualViewport. The layout viewport is the owner Window’s viewport.

For the purpose of the requirements in this specification, elements that have a computed value of the display property that is table-column or table-column-group must be considered to have an associated box (the column or column group, respectively).

The term SVG layout box refers to a box generated by an SVG element which does not correspond to a CSS-defined display type. (Such as the box generated by a rect element.)

The term transforms refers to SVG transforms and CSS transforms. [SVG11] [CSS-TRANSFORMS-1]

When a method or an attribute is said to call another method or attribute, the user agent must invoke its internal API for that attribute or method so that e.g. the author can’t change the behavior by overriding attributes or methods with custom properties or functions in ECMAScript.

Unless otherwise stated, all string comparisons use is.

2.1. CSS pixels

All coordinates and dimensions for the APIs defined in this specification are in CSS pixels, unless otherwise specified. [CSS-VALUES]

Note: This does not apply to e.g. matchMedia() as the units are explicitly given there.

2.2. Zooming

There are two kinds of zoom, page zoom which affects the size of the initial viewport, and the visual viewport scale factor which acts like a magnifying glass and does not affect the initial viewport or actual viewport. [CSS-DEVICE-ADAPT]

Note: The "scale factor" is often referred to as "pinch-zoom"; however, it can be affected through means other than pinch-zooming. e.g. The user agent may zooms in on a focused input element to make it legible.

2.3. Web-exposed screen information

User agents may choose to hide information about the screen of the output device, in order to protect the user’s privacy. In order to do so in a consistent manner across APIs, this specification defines the following terms, each having a width and a height, the origin being the top left corner, and the x- and y-coordinates increase rightwards and downwards, respectively.

The Web-exposed screen area must return the result of the following algorithm:

1. Let target be this’s relevant global object’s browsing context.

2. Let emulated screen area be the WebDriver BiDi emulated total screen area of target.

3. If emulated screen area is not null, return emulated screen area.

4. Otherwise, return one of the following:

   • The area of the output device, in CSS pixels.

   • The area of the viewport, in CSS pixels.

The Web-exposed available screen area must return the result of the following algorithm:

1. Let target be this’s relevant global object’s browsing context.

2. Let emulated screen area be the WebDriver BiDi emulated available screen area for target.

3. If emulated screen area is not null, return emulated screen area.

4. Otherwise, return one of the following:

   • The available area of the rendering surface of the output device, in CSS pixels.

   • The area of the output device, in CSS pixels.

   • The area of the viewport, in CSS pixels.

3. Common Infrastructure

This specification depends on the WHATWG Infra standard. [INFRA]

3.1. Scrolling

Scroll is completed when the scroll position has no more pending updates or translations and the user has completed their gesture. Scroll position updates include smooth or instant mouse wheel scrolling, keyboard scrolling, scroll-snap events, or other APIs and gestures which cause the scroll position to update and possibly interpolate. User gestures like touch panning or trackpad scrolling aren’t complete until pointers or keys have released.

When a user agent is to perform a smooth scroll of a scrolling box box to position, it must update the scroll position of box in a user-agent-defined fashion over a user-agent-defined amount of time. When the scroll is completed, the scroll position of box must be position. The scroll can also be aborted, either by an algorithm or by the user.

When a user agent is to perform an instant scroll of a scrolling box box to position, it must update the scroll position of box to position.

To scroll to the beginning of the document for a document document, follow these steps:

1. Let viewport be the viewport that is associated with document.
2. Let position be the scroll position viewport would have by aligning the beginning edges of the scrolling area with the beginning edges of viewport.
3. If position is the same as viewport’s current scroll position, and viewport does not have an ongoing smooth scroll, abort these steps.
4. Perform a scroll of viewport to position, and document’s root element as the associated element, if there is one, or null otherwise.

Note: This algorithm is used when navigating to the #top fragment identifier, as defined in HTML. [HTML]

3.2. WebIDL values

When asked to normalize non-finite values for a value x, if x is one of the three special floating point literal values (Infinity, -Infinity or NaN), then x must be changed to the value 0. [WEBIDL]

4. Extensions to the Window Interface

enum ScrollBehavior { "auto", "instant", "smooth" };

dictionary ScrollOptions {
    ScrollBehavior behavior = "auto";
};
dictionary ScrollToOptions : ScrollOptions {
    unrestricted double left;
    unrestricted double top;
};

partial interface Window {
    [NewObject] MediaQueryList matchMedia(CSSOMString query);
    [SameObject, Replaceable] readonly attribute Screen screen;
    [SameObject, Replaceable] readonly attribute VisualViewport? visualViewport;

    // browsing context
    undefined moveTo(long x, long y);
    undefined moveBy(long x, long y);
    undefined resizeTo(long width, long height);
    undefined resizeBy(long x, long y);

    // viewport
    [Replaceable] readonly attribute long innerWidth;
    [Replaceable] readonly attribute long innerHeight;

    // viewport scrolling
    [Replaceable] readonly attribute double scrollX;
    [Replaceable] readonly attribute double pageXOffset;
    [Replaceable] readonly attribute double scrollY;
    [Replaceable] readonly attribute double pageYOffset;
    Promise<undefined> scroll(optional ScrollToOptions options = {});
    Promise<undefined> scroll(unrestricted double x, unrestricted double y);
    Promise<undefined> scrollTo(optional ScrollToOptions options = {});
    Promise<undefined> scrollTo(unrestricted double x, unrestricted double y);
    Promise<undefined> scrollBy(optional ScrollToOptions options = {});
    Promise<undefined> scrollBy(unrestricted double x, unrestricted double y);

    // client
    [Replaceable] readonly attribute long screenX;
    [Replaceable] readonly attribute long screenLeft;
    [Replaceable] readonly attribute long screenY;
    [Replaceable] readonly attribute long screenTop;
    [Replaceable] readonly attribute long outerWidth;
    [Replaceable] readonly attribute long outerHeight;
    [Replaceable] readonly attribute double devicePixelRatio;
};

Should the scroll methods above return a result object and if so what information should they provide? #12495

When the matchMedia(query) method is invoked these steps must be run:

1. Let parsed media query list be the result of parsing query.
2. Return a new MediaQueryList object, with this’s associated Document as the document, with parsed media query list as its associated media query list.

The screen attribute must return the Screen object associated with the Window object.

Note: Accessing screen through a WindowProxy object might yield different results when the Document is navigated.

If the associated document is fully active, the visualViewport attribute must return the VisualViewport object associated with the Window object’s associated document. Otherwise, it must return null.

Note: the VisualViewport object is only returned and useful for a window whose Document is currently being presented. If a reference is retained to a VisualViewport whose associated Document is not being currently presented, the values in that VisualViewport must not reveal any information about the browsing context.

The moveTo(x, y) method must follow these steps:

1. Optionally, return.

2. Let target be this’s relevant global object’s browsing context.

3. If target is not an auxiliary browsing context that was created by a script (as opposed to by an action of the user), then return.

4. If target’s top-level traversable’s Is Document Picture-in-Picture boolean is true, then return.

5. Optionally, clamp x and y in a user-agent-defined manner so that the window does not move outside the available space.

6. Move target’s window such that the window’s top left corner is at coordinates (x, y) relative to the top left corner of the output device, measured in CSS pixels of target. The positive axes are rightward and downward.

The moveBy(x, y) method must follow these steps:

1. Optionally, return.

2. Let target be this’s relevant global object’s browsing context.

3. If target is not an auxiliary browsing context that was created by a script (as opposed to by an action of the user), then return.

4. If target’s top-level traversable’s Is Document Picture-in-Picture boolean is true, then return.

5. Optionally, clamp x and y in a user-agent-defined manner so that the window does not move outside the available space.

6. Move target’s window x CSS pixels of target rightward and y CSS pixels of target downward.

The resizeTo(width, height) method must follow these steps:

1. Optionally, return.

2. Let target be this’s relevant global object’s browsing context.

3. If target is not an auxiliary browsing context that was created by a script (as opposed to by an action of the user), then return.

4. If target’s top-level traversable’s Is Document Picture-in-Picture boolean is true, then:

   1. If this’s relevant global object does not have transient activation, throw a "NotAllowedError" DOMException.

   2. Consume user activation given this’s relevant global object.

5. Optionally, clamp width and height in a user-agent-defined manner so that the window does not get too small or bigger than the available space.

6. Resize target’s window by moving its right and bottom edges such that the distance between the left and right edges of the viewport are width CSS pixels of target and the distance between the top and bottom edges of the viewport are height CSS pixels of target.

7. Optionally, move target’s window in a user-agent-defined manner so that it does not grow outside the available space.

The resizeBy(x, y) method must follow these steps:

1. Optionally, return.

2. Let target be this’s relevant global object’s browsing context.

3. If target is not an auxiliary browsing context that was created by a script (as opposed to by an action of the user), then return.

4. If target’s top-level traversable’s Is Document Picture-in-Picture boolean is true, then:

   1. If this’s relevant global object does not have transient activation, throw a "NotAllowedError" DOMException.

   2. Consume user activation given this’s relevant global object.

5. Optionally, clamp x and y in a user-agent-defined manner so that the window does not get too small or bigger than the available space.

6. Resize target’s window by moving its right edge x CSS pixels of target rightward and its bottom edge y CSS pixels of target downward.

7. Optionally, move target’s window in a user-agent-defined manner so that it does not grow outside the available space.

The innerWidth attribute must return the viewport width including the size of a rendered scroll bar (if any), or zero if there is no viewport.

var viewportWidth = innerWidth

The innerHeight attribute must return the viewport height including the size of a rendered scroll bar (if any), or zero if there is no viewport.

The scrollX attribute must return the x-coordinate, relative to the initial containing block origin, of the left of the viewport, or zero if there is no viewport.

The pageXOffset attribute must return the value returned by the scrollX attribute.

The scrollY attribute must return the y-coordinate, relative to the initial containing block origin, of the top of the viewport, or zero if there is no viewport.

The pageYOffset attribute must return the value returned by the scrollY attribute.

When the scroll() method is invoked these steps must be run:

1. If invoked with one argument, follow these substeps:

   1. Let options be the argument.

   2. Let x be the value of the left dictionary member of options, if present, or the viewport’s current scroll position on the x axis otherwise.

   3. Let y be the value of the top dictionary member of options, if present, or the viewport’s current scroll position on the y axis otherwise.

2. If invoked with two arguments, follow these substeps:

   1. Let options be null converted to a ScrollToOptions dictionary. [WEBIDL]

   2. Let x and y be the arguments, respectively.

3. Normalize non-finite values for x and y.

4. If there is no viewport, return a resolved Promise and abort the remaining steps.

5. Let viewport width be the width of the viewport excluding the width of the scroll bar, if any.

6. Let viewport height be the height of the viewport excluding the height of the scroll bar, if any.

7. If the viewport has rightward overflow direction

   Let x be max(0, min(x, viewport scrolling area width - viewport width)).

   If the viewport has leftward overflow direction

   Let x be min(0, max(x, viewport width - viewport scrolling area width)).

8. If the viewport has downward overflow direction

   Let y be max(0, min(y, viewport scrolling area height - viewport height)).

   If the viewport has upward overflow direction

   Let y be min(0, max(y, viewport height - viewport scrolling area height)).

9. Let position be the scroll position the viewport would have by aligning the x-coordinate x of the viewport scrolling area with the left of the viewport and aligning the y-coordinate y of the viewport scrolling area with the top of the viewport.

10. If position is the same as the viewport’s current scroll position, and the viewport does not have an ongoing smooth scroll, return a resolved Promise and abort the remaining steps.

11. Let document be the viewport’s associated Document.

12. Perform a scroll of the viewport to position, document’s root element as the associated element, if there is one, or null otherwise, and the scroll behavior being the value of the behavior dictionary member of options. Let scrollPromise be the Promise returned from this step.

13. Return scrollPromise.

    User agents do not agree whether this uses the (coordinated) viewport perform a scroll or the scrolling box perform a scroll on the layout viewport’s scrolling box.

When the scrollTo() method is invoked, the user agent must act as if the scroll() method was invoked with the same arguments.

When the scrollBy() method is invoked, the user agent must run these steps:

1. If invoked with two arguments, follow these substeps:

   1. Let options be null converted to a ScrollToOptions dictionary. [WEBIDL]

   2. Let x and y be the arguments, respectively.

   3. Let the left dictionary member of options have the value x.

   4. Let the top dictionary member of options have the value y.

2. Normalize non-finite values for the left and top dictionary members of options.

3. Add the value of scrollX to the left dictionary member.

4. Add the value of scrollY to the top dictionary member.

5. Return the Promise returned from scroll() after the method is invoked with options as the only argument.

The screenX and screenLeft attributes must return the x-coordinate, relative to the origin of the Web-exposed screen area, of the left of the client window as number of CSS pixels, or zero if there is no such thing.

The screenY and screenTop attributes must return the y-coordinate, relative to the origin of the screen of the Web-exposed screen area, of the top of the client window as number of CSS pixels, or zero if there is no such thing.

The outerWidth attribute must return the width of the client window. If there is no client window this attribute must return zero.

The outerHeight attribute must return the height of the client window. If there is no client window this attribute must return zero.

The devicePixelRatio attribute must return the result of the following determine the device pixel ratio algorithm:

1. If there is no output device, return 1 and abort these steps.

2. Let CSS pixel size be the size of a CSS pixel at the current page zoom and using a scale factor of 1.0.

3. Let device pixel size be the vertical size of a device pixel of the output device.

4. Return the result of dividing CSS pixel size by device pixel size.

4.1. The features argument to the open() method

HTML defines the open() method. This section defines behavior for position and size given in the features argument. [HTML]

To set up browsing context features for a browsing context target given a map tokenizedFeatures:

1. Let x be null.

2. Let y be null.

3. Let width be null.

4. Let height be null.

5. If tokenizedFeatures["left"] exists:

   1. Set x to the result of invoking the rules for parsing integers on tokenizedFeatures["left"].

   2. If x is an error, set x to 0.

   3. Optionally, clamp x in a user-agent-defined manner so that the window does not move outside the Web-exposed available screen area.

   4. Optionally, move target’s window such that the window’s left edge is at the horizontal coordinate x relative to the left edge of the Web-exposed screen area, measured in CSS pixels of target. The positive axis is rightward.

6. If tokenizedFeatures["top"] exists:

   1. Set y to the result of invoking the rules for parsing integers on tokenizedFeatures["top"].

   2. If y is an error, set y to 0.

   3. Optionally, clamp y in a user-agent-defined manner so that the window does not move outside the Web-exposed available screen area.

   4. Optionally, move target’s window such that the window’s top edge is at the vertical coordinate y relative to the top edge of the Web-exposed screen area, measured in CSS pixels of target. The positive axis is downward.

7. If tokenizedFeatures["width"] exists:

   1. Set width to the result of invoking the rules for parsing integers on tokenizedFeatures["width"].

   2. If width is an error, set width to 0.

   3. If width is not 0:

      1. Optionally, clamp width in a user-agent-defined manner so that the window does not get too small or bigger than the Web-exposed available screen area.

      2. Optionally, size target’s window by moving its right edge such that the distance between the left and right edges of the viewport are width CSS pixels of target.

      3. Optionally, move target’s window in a user-agent-defined manner so that it does not grow outside the Web-exposed available screen area.

8. If tokenizedFeatures["height"] exists:

   1. Set height to the result of invoking the rules for parsing integers on tokenizedFeatures["height"].

   2. If height is an error, set height to 0.

   3. If height is not 0:

      1. Optionally, clamp height in a user-agent-defined manner so that the window does not get too small or bigger than the Web-exposed available screen area.

      2. Optionally, size target’s window by moving its bottom edge such that the distance between the top and bottom edges of the viewport are height CSS pixels of target.

      3. Optionally, move target’s window in a user-agent-defined manner so that it does not grow outside the Web-exposed available screen area.

A supported open() feature name is one of the following:

width

The width of the viewport.

height

The height of the viewport.

left

The left position of the window.

top

The top position of the window.

4.2. The MediaQueryList Interface

This section integrates with the event loop defined in HTML. [HTML]

A MediaQueryList object has an associated media query list and an associated document set on creation.

A MediaQueryList object has an associated media which is the serialized form of the associated media query list.

A MediaQueryList object has an associated matches state which is true if the associated media query list matches the state of the document, and false otherwise.

When asked to evaluate media queries and report changes for a Document doc, run these steps:

1. For each MediaQueryList object target that has doc as its document, in the order they were created, oldest first, run these substeps:

   1. If target’s matches state has changed since the last time these steps were run, fire an event named change at target using MediaQueryListEvent, with its isTrusted attribute initialized to true, its media attribute initialized to target’s media, and its matches attribute initialized to target’s matches state.

function handleOrientationChange(event) {
    if(event.matches) // landscape
        …
    else
        …
}
var mql = matchMedia("(orientation:landscape)");
mql.onchange = handleOrientationChange;

[Exposed=Window]
interface MediaQueryList : EventTarget {
  readonly attribute CSSOMString media;
  readonly attribute boolean matches;
  undefined addListener(EventListener? callback);
  undefined removeListener(EventListener? callback);
           attribute EventHandler onchange;
};

The media attribute must return the associated media.

The matches attribute must return the associated matches state.

The addListener(callback) method, when invoked, must run these steps:

1. Add an event listener with this and an event listener whose type is change, and callback is callback.

The removeListener(callback) method, when invoked, must run these steps:

1. If this’s event listener list contains an event listener whose type is change, callback is callback, and capture is false, then remove an event listener with this and that event listener.

Note: This specification initially had a custom callback mechanism with addListener() and removeListener(), and the callback was invoked with the associated media query list as argument. Now the normal event mechanism is used instead. For backwards compatibility, the addListener() and removeListener() methods are basically aliases for addEventListener() and removeEventListener(), respectively, and the change event masquerades as a MediaQueryList.

The following are the event handlers (and their corresponding event handler event types) that must be supported, as event handler IDL attributes, by all objects implementing the MediaQueryList interface:

[Exposed=Window]
interface MediaQueryListEvent : Event {
  constructor(CSSOMString type, optional MediaQueryListEventInit eventInitDict = {});
  readonly attribute CSSOMString media;
  readonly attribute boolean matches;
};

dictionary MediaQueryListEventInit : EventInit {
  CSSOMString media = "";
  boolean matches = false;
};

The media attribute must return the value it was initialized to.

The matches attribute must return the value it was initialized to.

4.2.1. Event summary

This section is non-normative.

4.3. The Screen Interface

As its name suggests, the Screen interface represents information about the screen of the output device.

[Exposed=Window]
interface Screen {
  readonly attribute long availWidth;
  readonly attribute long availHeight;
  readonly attribute long width;
  readonly attribute long height;
  readonly attribute unsigned long colorDepth;
  readonly attribute unsigned long pixelDepth;
};

The availWidth attribute must return the width of the Web-exposed available screen area.

The availHeight attribute must return the height of the Web-exposed available screen area.

The width attribute must return the width of the Web-exposed screen area.

The height attribute must return the height of the Web-exposed screen area.

The colorDepth and pixelDepth attributes should return the number of bits allocated to colors for a pixel in the output device, excluding the alpha channel. If the user agent is not able to return the number of bits used by the output device, it should return the closest estimation such as, for example, the number of bits used by the frame buffer sent to the display or any internal representation that would be the closest to the value the output device would use. The user agent must return a value for these attributes at least equal to the value of the color media feature multiplied by three. If the different color components are not represented with the same number of bits, the returned value may be greater than three times the value of the color media feature. If the user agent does not know the color depth or does not want to return it for privacy considerations, it should return 24.

Note: The colorDepth and pixelDepth attributes return the same value for compatibility reasons.

Note: Some non-conforming implementations are known to return 32 instead of 24.

5. Extensions to the Document Interface

partial interface Document {
  Element? elementFromPoint(double x, double y);
  sequence<Element> elementsFromPoint(double x, double y);
  CaretPosition? caretPositionFromPoint(double x, double y, optional CaretPositionFromPointOptions options = {});
  readonly attribute Element? scrollingElement;
};

dictionary CaretPositionFromPointOptions {
  sequence<ShadowRoot> shadowRoots = [];
};

The elementFromPoint(x, y) method must follow these steps:

1. If either argument is negative, x is greater than the viewport width excluding the size of a rendered scroll bar (if any), or y is greater than the viewport height excluding the size of a rendered scroll bar (if any), or there is no viewport associated with the document, return null and terminate these steps.

2. If there is a box in the viewport that would be a target for hit testing at coordinates x,y, when applying the transforms that apply to the descendants of the viewport, return the associated element and terminate these steps.

3. If the document has a root element, return the root element and terminate these steps.

4. Return null.

Note: The elementFromPoint() method does not necessarily return the top-most painted element. For instance, an element can be excluded from being a target for hit testing by using the pointer-events CSS property.

The elementsFromPoint(x, y) method must follow these steps:

1. Let sequence be a new empty sequence.

2. If either argument is negative, x is greater than the viewport width excluding the size of a rendered scroll bar (if any), or y is greater than the viewport height excluding the size of a rendered scroll bar (if any), or there is no viewport associated with the document, return sequence and terminate these steps.

3. For each box in the viewport, in paint order, starting with the topmost box, that would be a target for hit testing at coordinates x,y even if nothing would be overlapping it, when applying the transforms that apply to the descendants of the viewport, append the associated element to sequence.

4. If the document has a root element, and the last item in sequence is not the root element, append the root element to sequence.

5. Return sequence.

The caretPositionFromPoint(x, y, options) method must return the result of running these steps:

1. If there is no viewport associated with the document, return null.

2. If either argument is negative, x is greater than the viewport width excluding the size of a rendered scroll bar (if any), y is greater than the viewport height excluding the size of a rendered scroll bar (if any) return null.

3. If at the coordinates x,y in the viewport no text insertion point indicator would have been inserted when applying the transforms that apply to the descendants of the viewport, return null.

4. If at the coordinates x,y in the viewport a text insertion point indicator would have been inserted in a text entry widget which is also a replaced element, when applying the transforms that apply to the descendants of the viewport, return a caret position with its properties set as follows:

   caret node

   The node corresponding to the text entry widget.

   caret offset

   The amount of 16-bit units to the left of where the text insertion point indicator would have inserted.

5. Otherwise:

   1. Let caretPosition be a tuple consisting of a caretPositionNode (a node) and a caretPositionOffset (a non-negative integer) for the position where the text insertion point indicator would have been inserted when applying the transforms that apply to the descendants of the viewport.

   2. Let startNode be the caretPositionNode of the caretPosition, and let startOffset be the caretPositionOffset of the caretPosition.

   3. While startNode is a node, startNode’s root is a shadow root, and startNode’s root is not a shadow-including inclusive ancestor of any of options["shadowRoots"], repeat these steps:

      1. Set startOffset to index of startNode’s root’s host.

      2. Set startNode to startNode’s root’s host’s parent.

   4. Return a caret position with its properties set as follows:

      1. caret node is set to startNode.

      2. caret offset is set to startOffset.

Note: This caret position is not live.

Note: The specifics of hit testing are out of scope of this specification and therefore the exact details of elementFromPoint() and caretPositionFromPoint() are therefore too. Hit testing will hopefully be defined in a future revision of CSS or HTML.

The scrollingElement attribute, on getting, must run these steps:

1. If the Document is in quirks mode, follow these substeps:

   1. If the body element exists, and it is not potentially scrollable in either axis, return the body element and abort these steps.

      For this purpose, a value of overflow:clip on the the body element’s parent element must be treated as overflow:hidden.

   2. Return null and abort these steps.

2. If there is a root element, return the root element and abort these steps.

3. Return null.

Note: For non-conforming user agents that always use the quirks mode behavior for scrollTop and scrollLeft, the scrollingElement attribute is expected to also always return the body element (or null if it does not exist). This API exists so that Web developers can use it to get the right element to use for scrolling APIs, without making assumptions about a particular user agent’s behavior or having to invoke a scroll to see which element scrolls the viewport.

Note: the body element is different from HTML’s document.body in that the latter can return a frameset element.

5.1. The CaretPosition Interface

A caret position gives the position of a text insertion point indicator. It always has an associated caret node and caret offset. It is represented by a CaretPosition object.

[Exposed=Window]
interface CaretPosition {
  readonly attribute Node offsetNode;
  readonly attribute unsigned long offset;
  [NewObject] DOMRect? getClientRect();
};

The offsetNode attribute must return the caret node.

The offset attribute must return the caret offset.

The getClientRect() method must follow these steps, aborting on the first step that returns a value:

1. If caret node is a text entry widget that is a replaced element, and that is in the document, return a scaled DOMRect object for the caret in the widget as represented by the caret offset value. The transforms that apply to the element and its ancestors are applied.

2. Otherwise:

   1. Let caretRange be a collapsed Range object whose start node and end node are set to caret node, and whose start offset and end offset are set to caret offset.

   2. Return the DOMRect object which is the result of invoking the getBoundingClientRect() method on caretRange.

Note: This DOMRect object is not live.

6. Extensions to the Element Interface

enum ScrollLogicalPosition { "start", "center", "end", "nearest" };
dictionary ScrollIntoViewOptions : ScrollOptions {
  ScrollLogicalPosition block = "start";
  ScrollLogicalPosition inline = "nearest";
  ScrollIntoViewContainer container = "all";
};

enum ScrollIntoViewContainer { "all", "nearest" };

dictionary CheckVisibilityOptions {
    boolean checkOpacity = false;
    boolean checkVisibilityCSS = false;
    boolean contentVisibilityAuto = false;
    boolean opacityProperty = false;
    boolean visibilityProperty = false;
};

partial interface Element {
  DOMRectList getClientRects();
  [NewObject] DOMRect getBoundingClientRect();

  boolean checkVisibility(optional CheckVisibilityOptions options = {});

  Promise<undefined> scrollIntoView(optional (boolean or ScrollIntoViewOptions) arg = {});
  Promise<undefined> scroll(optional ScrollToOptions options = {});
  Promise<undefined> scroll(unrestricted double x, unrestricted double y);
  Promise<undefined> scrollTo(optional ScrollToOptions options = {});
  Promise<undefined> scrollTo(unrestricted double x, unrestricted double y);
  Promise<undefined> scrollBy(optional ScrollToOptions options = {});
  Promise<undefined> scrollBy(unrestricted double x, unrestricted double y);
  attribute unrestricted double scrollTop;
  attribute unrestricted double scrollLeft;
  readonly attribute long scrollWidth;
  readonly attribute long scrollHeight;
  readonly attribute long clientTop;
  readonly attribute long clientLeft;
  readonly attribute long clientWidth;
  readonly attribute long clientHeight;
  readonly attribute double currentCSSZoom;
};

Should the scroll methods above return a result object and if so what information should they provide? #12495

Note: The checkOpacity and checkVisibilityCSS properties are historical names. These properties have aliases that match the new naming scheme, namely opacityProperty and visibilityProperty.

The getClientRects() method, when invoked, must return the result of the following algorithm:

1. If the element on which it was invoked does not have an associated box return an empty DOMRectList object and stop this algorithm.

2. If the element has an associated SVG layout box return a scaled DOMRectList object containing a single DOMRect object that describes the bounding box of the element as defined by the SVG specification, applying the transforms that apply to the element and its ancestors.

3. Return a DOMRectList object containing DOMRect objects in content order, one for each box fragment, describing its border area (including those with a height or width of zero) with the following constraints:

   • Apply the transforms that apply to the element and its ancestors.

   • If the element on which the method was invoked has a computed value for the display property of table or inline-table include both the table box and the caption box, if any, but not the anonymous container box.

   • Replace each anonymous block box with its child box(es) and repeat this until no anonymous block boxes are left in the final list.

Note: The DOMRect objects returned by getClientRects() are not live.

The getBoundingClientRect() method, when invoked on an element element, must return the result of getting the bounding box for element.

Note: The DOMRect object returned by getBoundingClientRect() is not live.

var example = document.getElementsByTagName("div")[0].getBoundingClientRect();
var exampleWidth = example.width;
var exampleHeight = example.height;

The scrollIntoView(arg) method must run these steps:

1. Let behavior be "auto".

2. Let block be "start".

3. Let inline be "nearest".

4. Let container be null.

5. If arg is a ScrollIntoViewOptions dictionary, then:

   1. Set behavior to the behavior dictionary member of options.

   2. Set block to the block dictionary member of options.

   3. Set inline to the inline dictionary member of options.

   4. If the container dictionary member of options is "nearest", set container to the element.

6. Otherwise, if arg is false, then set block to "end".

7. If the element does not have any associated box, or is not available to user-agent features, then return a resolved Promise and abort the remaining steps.

8. Scroll the element into view with behavior, block, inline, and container. Let scrollPromise be the Promise returned from this step

9. Optionally perform some other action that brings the element to the user’s attention.

10. Return scrollPromise.

<style>
    .scroller { overflow: auto; scroll-padding: 8px; }
    .slide { scroll-margin: 16px; scroll-snap-align: center; }
</style>
<div class="carousel">
    <div class="slides scroller">
        <div id="s1" class="slide">
        <div id="s2" class="slide">
        <div id="s3" class="slide">
    </div>
    <div class="markers">
        <button data-target="s1">1</button>
        <button data-target="s2">2</button>
        <button data-target="s3">3</button>
    </div>
</div>
<script>
    document.querySelector('.markers').addEventListener('click', (evt) => {
        const target = document.getElementById(evt.target.dataset.target);
        if (!target) return;
        // scrollIntoView correctly aligns target item respecting scroll-snap-align,
        // scroll-margin, and the scroll container's scroll-padding.
        target.scrollIntoView({
            // Only scroll the nearest scroll container.
            container: 'nearest',
            behavior: 'smooth'
        });
    });
</script>

The scroll() method must run these steps:

1. If invoked with one argument, follow these substeps:

   1. Let options be the argument.

   2. Normalize non-finite values for left and top dictionary members of options, if present.

   3. Let x be the value of the left dictionary member of options, if present, or the element’s current scroll position on the x axis otherwise.

   4. Let y be the value of the top dictionary member of options, if present, or the element’s current scroll position on the y axis otherwise.

2. If invoked with two arguments, follow these substeps:

   1. Let options be null converted to a ScrollToOptions dictionary. [WEBIDL]

   2. Let x and y be the arguments, respectively.

   3. Normalize non-finite values for x and y.

   4. Let the left dictionary member of options have the value x.

   5. Let the top dictionary member of options have the value y.

3. Let document be the element’s node document.

4. If document is not the active document, return a resolved Promise and abort the remaining steps.

5. Let window be the value of document’s defaultView attribute.

6. If window is null, return a resolved Promise and abort the remaining steps.

7. If the element is the root element and document is in quirks mode, return a resolved Promise and abort the remaining steps.

8. If the element is the root element, return the Promise returned by scroll() on window after the method is invoked with scrollX on window as first argument and y as second argument, and abort the remaining steps.

9. If the element is the body element, document is in quirks mode, and the element is not potentially scrollable in either axis, return the Promise returned by scroll() on window after the method is invoked with options as the only argument, and abort the remaining steps.

10. If the element does not have any associated box, the element has no associated scrolling box, or the element has no overflow, return a resolved Promise and abort the remaining steps.

11. Scroll the element to x,y, with the scroll behavior being the value of the behavior dictionary member of options. Let scrollPromise be the Promise returned from this step.

12. Return scrollPromise.

When the scrollTo() method is invoked, the user agent must act as if the scroll() method was invoked with the same arguments.

When the scrollBy() method is invoked, the user agent must run these steps:

1. If invoked with one argument, follow these substeps:

   1. Let options be the argument.

   2. Normalize non-finite values for left and top dictionary members of options, if present.

2. If invoked with two arguments, follow these substeps:

   1. Let options be null converted to a ScrollToOptions dictionary. [WEBIDL]

   2. Let x and y be the arguments, respectively.

   3. Normalize non-finite values for x and y.

   4. Let the left dictionary member of options have the value x.

   5. Let the top dictionary member of options have the value y.

3. Add the value of scrollLeft to the left dictionary member.

4. Add the value of scrollTop to the top dictionary member.

5. Return the Promise returned by scroll() after the method is invoked with options as the only argument.

The scrollTop attribute, on getting, must return the result of running these steps:

1. Let document be the element’s node document.

2. If document is not the active document, return zero and terminate these steps.

3. Let window be the value of document’s defaultView attribute.

4. If window is null, return zero and terminate these steps.

5. If the element is the root element and document is in quirks mode, return zero and terminate these steps.

6. If the element is the root element return the value of scrollY on window.

7. If the element is the body element, document is in quirks mode, and the element is not potentially scrollable in at least one axis, return the value of scrollY on window.

8. If the element does not have any associated box, return zero and terminate these steps.

9. Return the y-coordinate of the scrolling area at the alignment point with the top of the padding edge of the element.

When setting the scrollTop attribute these steps must be run:

1. Let y be the given value.

2. Normalize non-finite values for y.

3. Let document be the element’s node document.

4. If document is not the active document, terminate these steps.

5. Let window be the value of document’s defaultView attribute.

6. If window is null, terminate these steps.

7. If the element is the root element and document is in quirks mode, terminate these steps.

8. If the element is the root element invoke scroll() on window with scrollX on window as first argument and y as second argument, and terminate these steps.

9. If the element is the body element, document is in quirks mode, and the element is not potentially scrollable in at least one axis, invoke scroll() on window with scrollX as first argument and y as second argument, and terminate these steps.

10. If the element does not have any associated box, the element has no associated scrolling box, or the element has no overflow, terminate these steps.

11. Scroll the element to scrollLeft,y, with the scroll behavior being "auto".

The scrollLeft attribute, on getting, must return the result of running these steps:

1. Let document be the element’s node document.

2. If document is not the active document, return zero and terminate these steps.

3. Let window be the value of document’s defaultView attribute.

4. If window is null, return zero and terminate these steps.

5. If the element is the root element and document is in quirks mode, return zero and terminate these steps.

6. If the element is the root element return the value of scrollX on window.

7. If the element is the body element, document is in quirks mode, and the element is not potentially scrollable in at least one axis, return the value of scrollX on window.

8. If the element does not have any associated box, return zero and terminate these steps.

9. Return the x-coordinate of the scrolling area at the alignment point with the left of the padding edge of the element.

When setting the scrollLeft attribute these steps must be run:

1. Let x be the given value.

2. Normalize non-finite values for x.

3. Let document be the element’s node document.

4. If document is not the active document, terminate these steps.

5. Let window be the value of document’s defaultView attribute.

6. If window is null, terminate these steps.

7. If the element is the root element and document is in quirks mode, terminate these steps.

8. If the element is the root element invoke scroll() on window with x as first argument and scrollY on window as second argument, and terminate these steps.

9. If the element is the body element, document is in quirks mode, and the element is not potentially scrollable in at least one axis, invoke scroll() on window with x as first argument and scrollY on window as second argument, and terminate these steps.

10. If the element does not have any associated box, the element has no associated scrolling box, or the element has no overflow, terminate these steps.

11. Scroll the element to x,scrollTop, with the scroll behavior being "auto".

The scrollWidth attribute must return the result of running these steps:

1. Let document be the element’s node document.

2. If document is not the active document, return zero and terminate these steps.

3. Let viewport width be the width of the viewport excluding the width of the scroll bar, if any, or zero if there is no viewport.

4. If the element is the root element and document is not in quirks mode return max(viewport scrolling area width, viewport width).

5. If the element is the body element, document is in quirks mode and the element is not potentially scrollable in the x axis, return max(viewport scrolling area width, viewport width).

6. If the element does not have any associated box return zero and terminate these steps.

7. Return the width of the element’s scrolling area.

The scrollHeight attribute must return the result of running these steps:

1. Let document be the element’s node document.

2. If document is not the active document, return zero and terminate these steps.

3. Let viewport height be the height of the viewport excluding the height of the scroll bar, if any, or zero if there is no viewport.

4. If the element is the root element and document is not in quirks mode return max(viewport scrolling area height, viewport height).

5. If the element is the body element, document is in quirks mode and the element is not potentially scrollable in the y axis, return max(viewport scrolling area height, viewport height).

6. If the element does not have any associated box return zero and terminate these steps.

7. Return the height of the element’s scrolling area.

The clientTop attribute must run these steps:

1. If the element has no associated box or if the box is inline, return zero.

2. Return the unscaled computed value of the border-top-width property plus the height of any scrollbar rendered between the top padding edge and the top border edge, ignoring any transforms that apply to the element and its ancestors.

The clientLeft attribute must run these steps:

1. If the element has no associated box or if the box is inline, return zero.

2. Return the unscaled computed value of the border-left-width property plus the width of any scrollbar rendered between the left padding edge and the left border edge, ignoring any transforms that apply to the element and its ancestors.

The clientWidth attribute must run these steps:

1. If the element has no associated box or if the box is inline, return zero.

2. If the element is the root element and the element’s node document is not in quirks mode, or if the element is the body element and the element’s node document is in quirks mode, return the viewport width excluding the size of a rendered scroll bar (if any).

3. Return the unscaled width of the padding edge excluding the width of any rendered scrollbar between the padding edge and the border edge, ignoring any transforms or that apply to the element and its ancestors.

The clientHeight attribute must run these steps:

1. If the element has no associated box or if the box is inline, return zero.

2. If the element is the root element and the element’s node document is not in quirks mode, or if the element is the body element and the element’s node document is in quirks mode, return the viewport height excluding the size of a rendered scroll bar (if any).

3. Return the unscaled height of the padding edge excluding the height of any rendered scrollbar between the padding edge and the border edge, ignoring any transforms that apply to the element and its ancestors.

The currentCSSZoom attribute must return the effective zoom of the element, or 1.0 if the element isn’t being rendered.

6.1. Element Scrolling Members

7. Extensions to the HTMLElement Interface

partial interface HTMLElement {
  readonly attribute Element? scrollParent;
  readonly attribute Element? offsetParent;
  readonly attribute long offsetTop;
  readonly attribute long offsetLeft;
  readonly attribute long offsetWidth;
  readonly attribute long offsetHeight;
};

The scrollParent attribute must return the result of running these steps:

1. If any of the following holds true, return null and terminate this algorithm:

   • The element does not have an associated box.

   • The element is the root element.

   • The element is the body element.

   • The element’s computed value of the position property is fixed and no ancestor establishes a fixed position containing block.

2. Let ancestor be the containing block of the element in the flat tree and repeat these substeps:

   1. If ancestor is the initial containing block, return the scrollingElement for the element’s document if it is not closed-shadow-hidden from the element, otherwise return null.

   2. If ancestor is not closed-shadow-hidden from the element, and is a scroll container, terminate this algorithm and return ancestor.

   3. If the computed value of the position property of ancestor is fixed, and no ancestor establishes a fixed position containing block, terminate this algorithm and return null.

   4. Let ancestor be the containing block of ancestor in the flat tree.

The offsetParent attribute must return the result of running these steps:

1. If any of the following holds true return null and terminate this algorithm:

   • The element does not have an associated box.

   • The element is the root element.

   • The element is the body element.

   • The element’s computed value of the position property is fixed and no ancestor establishes a fixed position containing block.

2. Let ancestor be the parent of the element in the flat tree and repeat these substeps:

   1. If ancestor is closed-shadow-hidden from the element, its computed value of the position property is fixed, and no ancestor establishes a fixed position containing block, terminate this algorithm and return null.

   2. If ancestor is not closed-shadow-hidden from the element and satisfies at least one of the following, terminate this algorithm and return ancestor.

      • The element is in a fixed position containing block, and ancestor is a containing block for fixed-positioned descendants.

      • The element is not in a fixed position containing block, and:

        • ancestor is a containing block of absolutely-positioned descendants (regardless of whether there are any absolutely-positioned descendants).

        • It is the body element.

        • The computed value of the position property of the element is static and the ancestor is one of the following HTML elements: td, th, or table.

      • The element has a different effective zoom than ancestor.

   3. If there is no more parent of ancestor in the flat tree, terminate this algorithm and return null.

   4. Let ancestor be the parent of ancestor in the flat tree.

The offsetTop attribute must return the result of running these steps:

1. If the element is the body element or does not have any associated box return zero and terminate this algorithm.

2. If the offsetParent of the element is null return the unscaled y-coordinate of the top border edge of the first box associated with the element, relative to the initial containing block origin, ignoring any transformsthat apply to the element and its ancestors and terminate this algorithm.

3. Return the unscaled result of subtracting the y-coordinate of the top padding edge of the first box associated with the offsetParent of the element from the y-coordinate of the top border edge of the first box associated with the element, relative to the initial containing block origin, ignoring any transforms that apply to the element and its ancestors.

   Note: An inline element that consists of multiple line boxes will only have its first box considered.

The offsetLeft attribute must return the result of running these steps:

1. If the element is the body element or does not have any associated box return zero and terminate this algorithm.

2. If the offsetParent of the element is null return the unscaled x-coordinate of the left border edge of the first box associated with the element, relative to the initial containing block origin, ignoring any transforms that apply to the element and its ancestors, and terminate this algorithm.

3. Return the unscaled result of subtracting the x-coordinate of the left padding edge of the first box associated with the offsetParent of the element from the x-coordinate of the left border edge of the first box associated with the element, relative to the initial containing block origin, ignoring any transforms that apply to the element and its ancestors.

The offsetWidth attribute must return the result of running these steps:

1. If the element does not have any associated box return zero and terminate this algorithm.

2. Return the unscaled width of the axis-aligned bounding box of the border boxes of all fragments generated by the element’s principal box, ignoring any transforms that apply to the element and its ancestors.

   If the element’s principal box is an inline-level box which was "split" by a block-level descendant, also include fragments generated by the block-level descendants, unless they are zero width or height.

The offsetHeight attribute must return the result of running these steps:

1. If the element does not have any associated box return zero and terminate this algorithm.

2. Return the unscaled height of the axis-aligned bounding box of the border boxes of all fragments generated by the element’s principal box, ignoring any transforms that apply to the element and its ancestors.

   If the element’s principal box is an inline-level box which was "split" by a block-level descendant, also include fragments generated by the block-level descendants, unless they are zero width or height.