CSSOM View Module

Editor’s Draft,

Specification Metadata
This version:
https://drafts.csswg.org/cssom-view/
Latest published version:
https://www.w3.org/TR/cssom-view-1/
Previous Versions:
Test Suite:
http://test.csswg.org/suites/cssom-view-1_dev/nightly-unstable/
Issue Tracking:
CSSWG Issues Repository
Inline In Spec
Editors:
(Apple Inc)
(Mozilla)
Former Editors:
(Opera Software AS)
Glenn Adams (Cox Communications, Inc.)
Anne van Kesteren (Opera Software ASA)
Suggest an Edit for this Spec:
GitHub Editor
Legacy issues list:
Bugzilla

Abstract

The APIs introduced by this specification provide authors with a way to inspect and manipulate the visual view of a document. This includes getting the position of element layout boxes, obtaining the width of the viewport through script, and also scrolling an element.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Please send feedback by filing issues in GitHub (preferred), including the spec code “cssom-view” in the title, like this: “[cssom-view] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

This document is governed by the 15 September 2020 W3C Process Document.

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]

The HTML body element is the first body HTML element child of the root HTML element html.

Content edge, padding edge, border edge, margin edge, and viewport are defined by CSS.

Elements and viewports have an associated scrolling box if the element or viewport has a scrolling mechanism, or it overflows its content area and the used value of the overflow-x or overflow-y property is not hidden or clip. [CSS3-BOX]

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

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 Overflow and Scroll Positions.

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.

If the overflow directions are… For a viewport For an element
rightward and downward
top edge
The top edge of the initial containing block.
right edge
The right-most edge of the right edge of the initial containing block and the right margin edge of all of the viewport’s descendants' boxes.
bottom edge
The bottom-most edge of the bottom edge of the initial containing block and the bottom margin edge of all of the viewport’s descendants' boxes.
left edge
The left edge of the initial containing block.
top edge
The element’s top padding edge.
right edge
The right-most edge of the element’s right padding edge and the right margin edge of all of the element’s descendants' boxes, excluding boxes that have an ancestor of the element as their containing block.
bottom edge
The bottom-most edge of the element’s bottom padding edge and the bottom margin edge of all of the element’s descendants' boxes, excluding boxes that have an ancestor of the element as their containing block.
left edge
The element’s left padding edge.
leftward and downward
top edge
The top edge of the initial containing block.
right edge
The right edge of the initial containing block.
bottom edge
The bottom-most edge of the bottom edge of the initial containing block and the bottom margin edge of all of the viewport’s descendants' boxes.
left edge
The left-most edge of the left edge of the initial containing block and the left margin edge of all of the viewport’s descendants' boxes.
top edge
The element’s top padding edge.
right edge
The element’s right padding edge.
bottom edge
The bottom-most edge of the element’s bottom padding edge and the bottom margin edge of all of the element’s descendants' boxes, excluding boxes that have an ancestor of the element as their containing block.
left edge
The left-most edge of the element’s left padding edge and the left margin edge of all of the element’s descendants' boxes, excluding boxes that have an ancestor of the element as their containing block.
leftward and upward
top edge
The top-most edge of the top edge of the initial containing block and the top margin edge of all of the viewport’s descendants' boxes.
right edge
The right edge of the initial containing block.
bottom edge
The bottom edge of the initial containing block.
left edge
The left-most edge of the left edge of the initial containing block and the left margin edge of all of the viewport’s descendants' boxes.
top edge
The top-most edge of the element’s top padding edge and the top margin edge of all of the element’s descendants' boxes, excluding boxes that have an ancestor of the element as their containing block.
right edge
The element’s right padding edge.
bottom edge
The element’s bottom padding edge.
left edge
The left-most edge of the element’s left padding edge and the left margin edge of all of the element’s descendants' boxes, excluding boxes that have an ancestor of the element as their containing block.
rightward and upward
top edge
The top-most edge of the top edge of the initial containing block and the top margin edge of all of the viewport’s descendants' boxes.
right edge
The right-most edge of the right edge of the initial containing block and the right margin edge of all of the viewport’s descendants' boxes.
bottom edge
The bottom edge of the initial containing block.
left edge
The left edge of the initial containing block.
top edge
The top-most edge of the element’s top padding edge and the top margin edge of all of the element’s descendants' boxes, excluding boxes that have an ancestor of the element as their containing block.
right edge
The right-most edge of the element’s right padding edge and the right margin edge of all of the element’s descendants' boxes, excluding boxes that have an ancestor of the element as their containing block.
bottom edge
The element’s bottom padding edge.
left edge
The element’s left padding edge.

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 term CSS layout box refers to the same term in CSS. 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 CSS layout box (the column or column group, respectively).

The term SVG layout box refers to the same term in SVG.

The terms CSS layout box and SVG layout box are not currently defined by CSS or SVG.

The term layout box refers to either a CSS layout box or an SVG layout box.

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, string comparisons are done in a case-sensitive manner.

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 pinch zoom which acts like a magnifying glass and does not affect the initial viewport or actual viewport. [CSS-DEVICE-ADAPT]

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 is one of the following:

The Web-exposed available screen area is one of the following:

3. Common Infrastructure

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

3.1. Scrolling

When a user agent is to perform a scroll of a scrolling box box, to a given position position, an associated element element and optionally a scroll behavior behavior (which is "auto" if omitted), the following steps must be run:

  1. Abort any ongoing smooth scroll for box.
  2. If the user agent honors the scroll-behavior property and one of the following are true:
    • behavior is "auto" and element is not null and its computed value of the scroll-behavior property is smooth
    • behavior is smooth
    ...then perform a smooth scroll of box to position. Otherwise, perform an instant scroll of box to position.

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

ScrollToOptions/behavior

In all current engines.

FirefoxYesSafariYesChrome45+
Opera32+Edge79+
Edge (Legacy)NoneIENone
Firefox for AndroidYesiOS SafariYesChrome for Android45+Android WebView45+Samsung Internet5.0+Opera Mobile32+

ScrollToOptions/left

In all current engines.

FirefoxYesSafariYesChrome45+
Opera32+Edge79+
Edge (Legacy)NoneIENone
Firefox for AndroidYesiOS SafariYesChrome for Android45+Android WebView45+Samsung Internet5.0+Opera Mobile32+

ScrollToOptions/top

In all current engines.

FirefoxYesSafariYesChrome45+
Opera32+Edge79+
Edge (Legacy)NoneIENone
Firefox for AndroidYesiOS SafariYesChrome for Android45+Android WebView45+Samsung Internet5.0+Opera Mobile32+

ScrollToOptions

In all current engines.

FirefoxYesSafariYesChrome45+
Opera32+Edge79+
Edge (Legacy)NoneIENone
Firefox for AndroidYesiOS SafariYesChrome for Android45+Android WebView45+Samsung Internet5.0+Opera Mobile32+
enum ScrollBehavior { "auto", "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;

    // 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;
    undefined scroll(optional ScrollToOptions options = {});
    undefined scroll(unrestricted double x, unrestricted double y);
    undefined scrollTo(optional ScrollToOptions options = {});
    undefined scrollTo(unrestricted double x, unrestricted double y);
    undefined scrollBy(optional ScrollToOptions options = {});
    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;
};

Window/matchMedia

In all current engines.

Firefox6+Safari5.1+Chrome9+
Opera12.1+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android6+iOS Safari5+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile12.1+

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 the context object’s associated Document as the document, with parsed media query list as its associated media query list.

Window/screen

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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.

Window/moveTo

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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

  1. Optionally, terminate these steps.

  2. Let target be the browsing context of the context object.

  3. Let source be the responsible browsing context of the incumbent settings object.

  4. If source is not allowed to resize and move target, terminate these steps.

  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.

Window/moveBy

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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

  1. Optionally, terminate these steps.

  2. Let target be the browsing context of the context object.

  3. Let source be the responsible browsing context of the incumbent settings object.

  4. If source is not allowed to resize and move target, terminate these steps.

  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.

Window/resizeTo

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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

  1. Optionally, terminate these steps.

  2. Let target be the browsing context of the context object.

  3. Let source be the responsible browsing context of the incumbent settings object.

  4. If source is not allowed to resize and move target, terminate these steps.

  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.

Window/resizeBy

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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

  1. Optionally, terminate these steps.

  2. Let target be the browsing context of the context object.

  3. Let source be the responsible browsing context of the incumbent settings object.

  4. If source is not allowed to resize and move target, terminate these steps.

  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.

A browsing context A is allowed to resize and move a browsing context B if all the following conditions are met:

Window/innerWidth

In all current engines.

Firefox1+Safari3+Chrome1+
Opera9+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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.

The following snippet shows how to obtain the width of the viewport:
var viewportWidth = innerWidth

Window/innerHeight

In all current engines.

Firefox1+Safari3+Chrome1+
Opera9+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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.

Window/scrollX

In all current engines.

Firefox1+Safari1+Chrome1+
Opera9.6+Edge79+
Edge (Legacy)12+IENone
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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.

Window/pageXOffset

In all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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

Window/scrollY

In all current engines.

Firefox1+Safari1+Chrome1+
Opera9.6+Edge79+
Edge (Legacy)12+IENone
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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.

Window/pageYOffset

In all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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

Window/scroll

In all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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, abort these 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, abort these 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.

Window/scrollTo

In all current engines.

Firefox1+Safari1+Chrome1+
Opera4+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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

Window/scrollBy

In all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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. Act as if the scroll() method was invoked with options as the only argument.

Window/screenLeft

In all current engines.

Firefox64+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android64+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

Window/screenX

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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.

Window/screenTop

In all current engines.

Firefox64+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android64+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

Window/screenY

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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.

Window/outerWidth

In all current engines.

Firefox1+Safari3+Chrome1+
Opera9+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari3+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera Mobile10.1+

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

Window/outerHeight

In all current engines.

Firefox1+Safari3+Chrome1+
Opera9+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari3+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera Mobile10.1+

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

Window/devicePixelRatio

In all current engines.

Firefox18+Safari3+Chrome1+
Opera11.1+Edge79+
Edge (Legacy)12+IE11
Firefox for Android18+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile11.1+

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 scale factor and at a pinch zoom 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

Window/open

In all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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

MediaQueryList

In all current engines.

Firefox6+Safari5.1+Chrome9+
Opera12.1+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android6+iOS Safari5+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera MobileYes

MediaQueryListEvent

In all current engines.

Firefox55+Safari14+Chrome39+
Opera26+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android55+iOS Safari14+Chrome for Android39+Android WebView39+Samsung Internet4.0+Opera Mobile26+

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 at target using the MediaQueryListEvent constructor, with its type attribute initialized to change, its isTrusted attribute initialized to true, its media attribute initialized to target’s media, and its matches attribute initialized to target’s matches state.
A simple piece of code that detects changes in the orientation of the viewport can be written as follows:
function handleOrientationChange(event) {
    if(event.matches) // landscapeelse}
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;
};

MediaQueryList/media

In all current engines.

Firefox6+Safari5.1+Chrome9+
Opera12.1+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android6+iOS Safari5+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera MobileYes

The media attribute must return the associated media.

MediaQueryList/matches

In all current engines.

Firefox6+Safari5.1+Chrome9+
Opera12.1+Edge79+
Edge (Legacy)12+IE10+
Firefox for Android6+iOS Safari5+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera MobileYes

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 the context object and an event listener whose type is change, and callback is callback.

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

  1. If the context object’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 the context object 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:

Event handler Event handler event type

MediaQueryList/onchange

In all current engines.

Firefox55+Safari14+Chrome45+
OperaYesEdge79+
Edge (Legacy)NoneIENone
Firefox for Android55+iOS Safari14+Chrome for Android45+Android WebView45+Samsung Internet5.0+Opera MobileYes
onchange
change

MediaQueryListEvent/MediaQueryListEvent

In all current engines.

Firefox55+Safari14+Chrome39+
Opera26+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android55+iOS Safari14+Chrome for Android39+Android WebView39+Samsung Internet4.0+Opera Mobile26+
[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;
};

MediaQueryListEvent/media

In all current engines.

Firefox55+Safari14+Chrome39+
Opera26+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android55+iOS Safari14+Chrome for Android39+Android WebView39+Samsung Internet4.0+Opera Mobile26+

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

MediaQueryListEvent/matches

In all current engines.

Firefox55+Safari14+Chrome39+
Opera26+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android55+iOS Safari14+Chrome for Android39+Android WebView39+Samsung Internet4.0+Opera Mobile26+

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

4.2.1. Event summary

This section is non-normative.

Event Interface Interesting targets Description
change Event MediaQueryList Fired at the MediaQueryList when the matches state changes.

4.3. The Screen Interface

Screen

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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;
};

Screen/availWidth

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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

Screen/availHeight

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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

Screen/width

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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

Screen/height

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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

Screen/colorDepth

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

Screen/pixelDepth

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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 color media query 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 color media query. 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

Document

In all current engines.

Firefox1+Safari1+Chrome1+
Opera3+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+
partial interface Document {
  Element? elementFromPoint(double x, double y);
  sequence<Element> elementsFromPoint(double x, double y);
  CaretPosition? caretPositionFromPoint(double x, double y);
  readonly attribute Element? scrollingElement;
};

Document/elementFromPoint

In all current engines.

Firefox3+Safari4+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari3.2+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile12.1+

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 layout 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.

Document/elementsFromPoint

In all current engines.

Firefox46+Safari11.1+Chrome43+
Opera30+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android46+iOS Safari11.3+Chrome for Android43+Android WebView43+Samsung Internet4.0+Opera Mobile30+

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 layout 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.

Document/caretPositionFromPoint

In only one current engine.

Firefox20+SafariNoneChromeNone
OperaNoneEdgeNone
Edge (Legacy)NoneIENone
Firefox for Android20+iOS SafariNoneChrome for AndroidNoneAndroid WebViewNoneSamsung InternetNoneOpera MobileNone

The caretPositionFromPoint(x, y) 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.
    caret range
    null
  5. Otherwise, return a caret position where the caret range is a collapsed Range object 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, and the other properties are set as follows:

    caret node
    The startContainer of the caret range.
    caret offset
    The startOffset of the caret range.

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.

Document/scrollingElement

In all current engines.

Firefox48+Safari9+Chrome44+
Opera31+Edge79+
Edge (Legacy)12+IENone
Firefox for Android48+iOS Safari9+Chrome for Android44+Android WebView44+Samsung Internet4.0+Opera Mobile32+

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

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

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

      For this purpose, a value of overflow:clip on the the HTML 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 HTML 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 HTML body element is different from HTML’s document.body in that the latter can return a frameset element.

5.1. The CaretPosition Interface

CaretPosition

In only one current engine.

Firefox20+SafariNoneChromeNone
OperaNoneEdgeNone
Edge (Legacy)NoneIENone
Firefox for Android20+iOS SafariNoneChrome for AndroidNoneAndroid WebViewNoneSamsung InternetNoneOpera MobileNone

A caret position gives the position of a text insertion point indicator. It always has an associated caret node, caret offset, and caret range. 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 range is not null:

    1. Let list be the result of invoking the getClientRects() method on the range.

    2. If list is empty, return null.

    3. Return the DOMRect object in list at index 0.

  2. If caret node is a text entry widget that is a replaced element, and that is in the document, return a 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.

  3. Return null.

Note: This DOMRect object is not live.

6. Extensions to the Element Interface

Element

In all current engines.

Firefox1+Safari1+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

Element/scroll

In all current engines.

Firefox36+Safari10.1+Chrome61+
Opera48+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android36+iOS Safari10.3+Chrome for Android61+Android WebView61+Samsung Internet8.0+Opera Mobile45+

Element/scrollBy

In all current engines.

Firefox36+Safari10.1+Chrome61+
Opera48+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android36+iOS Safari10.3+Chrome for Android61+Android WebView61+Samsung Internet8.0+Opera Mobile45+

Element/scrollTo

In all current engines.

Firefox36+Safari10.1+Chrome61+
Opera48+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android36+iOS Safari10.3+Chrome for Android61+Android WebView61+Samsung Internet8.0+Opera Mobile45+
enum ScrollLogicalPosition { "start", "center", "end", "nearest" };
dictionary ScrollIntoViewOptions : ScrollOptions {
  ScrollLogicalPosition block = "start";
  ScrollLogicalPosition inline = "nearest";
};

partial interface Element {
  DOMRectList getClientRects();
  [NewObject] DOMRect getBoundingClientRect();
  undefined scrollIntoView(optional (boolean or ScrollIntoViewOptions) arg = {});
  undefined scroll(optional ScrollToOptions options = {});
  undefined scroll(unrestricted double x, unrestricted double y);
  undefined scrollTo(optional ScrollToOptions options = {});
  undefined scrollTo(unrestricted double x, unrestricted double y);
  undefined scrollBy(optional ScrollToOptions options = {});
  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;
};

Element/getClientRects

In all current engines.

Firefox3+Safari4+Chrome2+
Opera9.5+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android4+iOS Safari3.2+Chrome for Android18+Android WebView2+Samsung Internet1.0+Opera Mobile10.1+

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 layout box return an empty DOMRectList object and stop this algorithm.

  2. If the element has an associated SVG layout box return a 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.

Element/getBoundingClientRect

In all current engines.

Firefox3+Safari4+Chrome2+
Opera9.5+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari3.2+Chrome for Android18+Android WebView2+Samsung Internet1.0+Opera Mobile10.1+

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

  1. Let list be the result of invoking getClientRects() on the same element this method was invoked on.

  2. If the list is empty return a DOMRect object whose x, y, width and height members are zero.

  3. If all rectangles in list have zero width or height, return the first rectangle in list.

  4. Otherwise, return a DOMRect object describing the smallest rectangle that includes all of the rectangles in list of which the height or width is not zero.

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

The following snippet gets the dimensions of the first div element in a document:
var example = document.getElementsByTagName("div")[0].getBoundingClientRect();
var exampleWidth = example.width;
var exampleHeight = example.height;

Element/scrollIntoView

In all current engines.

Firefox1+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)NoneIE5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

The scrollIntoView(arg) method must run these steps:

  1. Let behavior be "auto".

  2. Let block be "start".

  3. Let inline be "nearest".

  4. 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.

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

  6. If the element does not have any associated layout box, then return.

  7. Scroll the element into view with behavior, block, and inline.

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

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, 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 HTML body element, document is in quirks mode, and the element is not potentially scrollable, invoke scroll() on window with options as the only argument, and terminate these steps.

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

  11. Scroll the element to x,y, with the scroll behavior being the value of the behavior dictionary member of options.

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. Act as if the scroll() method was invoked with options as the only argument.

Element/scrollTop

In all current engines.

Firefox1+Safari1+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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 HTML body element, document is in quirks mode, and the element is not potentially scrollable, return the value of scrollY on window.

  8. If the element does not have any associated CSS layout 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 HTML body element, document is in quirks mode, and the element is not potentially scrollable, 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 CSS layout 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".

Element/scrollLeft

In all current engines.

Firefox1+Safari1+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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 HTML body element, document is in quirks mode, and the element is not potentially scrollable, return the value of scrollX on window.

  8. If the element does not have any associated CSS layout 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 HTML body element, document is in quirks mode, and the element is not potentially scrollable, 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 CSS layout 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".

Element/scrollWidth

In all current engines.

Firefox1+Safari1+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12.1+

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 HTML body element, document is in quirks mode and the element is not potentially scrollable, return max(viewport scrolling area width, viewport width).

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

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

Element/scrollHeight

In all current engines.

Firefox21+Safari1+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android21+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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 HTML body element, document is in quirks mode and the element is not potentially scrollable, return max(viewport scrolling area height, viewport height).

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

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

Element/clientTop

In all current engines.

Firefox1+Safari3+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

The clientTop attribute must run these steps:

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

  2. Return the 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.

Element/clientLeft

In all current engines.

Firefox1+Safari3+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

The clientLeft attribute must run these steps:

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

  2. Return the 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.

Element/clientWidth

In all current engines.

Firefox1+Safari3+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

The clientWidth attribute must run these steps:

  1. If the element has no associated CSS layout box or if the CSS layout 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 HTML 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 width of the padding edge excluding the width of any rendered scrollbar between the padding edge and the border edge, ignoring any transforms that apply to the element and its ancestors.

Element/clientHeight

In all current engines.

Firefox1+Safari3+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

The clientHeight attribute must run these steps:

  1. If the element has no associated CSS layout box or if the CSS layout 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 HTML 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 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.

6.1. Element Scrolling Members

To scroll an element into view element, with a scroll behavior behavior, a block flow direction position block, and an inline base direction position inline, means to run these steps for each ancestor element or viewport that establishes a scrolling box scrolling box, in order of innermost to outermost scrolling box:

  1. If the Document associated with element is not same origin with the Document associated with the element or viewport associated with box, terminate these steps.

  2. Let element bounding border box be the box that the return value of invoking getBoundingClientRect() on element represents.

  3. Let scrolling box edge A be the beginning edge in the block flow direction of scrolling box, and let element edge A be element bounding border box’s edge on the same physical side as that of scrolling box edge A.

  4. Let scrolling box edge B be the ending edge in the block flow direction of scrolling box, and let element edge B be element bounding border box’s edge on the same physical side as that of scrolling box edge B.

  5. Let scrolling box edge C be the beginning edge in the inline base direction of scrolling box, and let element edge C be element bounding border box’s edge on the same physical side as that of scrolling box edge C.

  6. Let scrolling box edge D be the ending edge in the inline base direction of scrolling box, and let element edge D be element bounding border box’s edge on the same physical side as that of scrolling box edge D.

  7. Let element height be the distance between element edge A and element edge B.

  8. Let scrolling box height be the distance between scrolling box edge A and scrolling box edge B.

  9. Let element width be the distance between element edge C and element edge D.

  10. Let scrolling box width be the distance between scrolling box edge C and scrolling box edge D.

  11. Let position be the scroll position scrolling box would have by following these steps:

    1. If block is "start", then align element edge A with scrolling box edge A.

    2. Otherwise, if block is "end", then align element edge B with scrolling box edge B.

    3. Otherwise, if block is "center", then align the center of element bounding border box with the center of scrolling box in scrolling box’s block flow direction.

    4. Otherwise, block is "nearest":

      If element edge A and element edge B are both outside scrolling box edge A and scrolling box edge B
      Do nothing.
      If element edge A is outside scrolling box edge A and element height is less than scrolling box height
      If element edge B is outside scrolling box edge B and element height is greater than scrolling box height
      Align element edge A with scrolling box edge A.
      If element edge A is outside scrolling box edge A and element height is greater than scrolling box height
      If element edge B is outside scrolling box edge B and element height is less than scrolling box height
      Align element edge B with scrolling box edge B.
    5. If inline is "start", then align element edge C with scrolling box edge C.

    6. Otherwise, if inline is "end", then align element edge D with scrolling box edge D.

    7. Otherwise, if inline is "center", then align the center of element bounding border box with the center of scrolling box in scrolling box’s inline base direction.

    8. Otherwise, inline is "nearest":

      If element edge C and element edge D are both outside scrolling box edge C and scrolling box edge D
      Do nothing.
      If element edge C is outside scrolling box edge C and element width is less than scrolling box width
      If element edge D is outside scrolling box edge D and element width is greater than scrolling box width
      Align element edge C with scrolling box edge C.
      If element edge C is outside scrolling box edge C and element width is greater than scrolling box width
      If element edge D is outside scrolling box edge D and element width is less than scrolling box width
      Align element edge D with scrolling box edge D.
  12. If position is the same as scrolling box’s current scroll position, and scrolling box does not have an ongoing smooth scroll, then return.

  13. If scrolling box is associated with an element
    Let associated element be the element.
    If scrolling box is associated with a viewport
    Let document be the viewport’s associated Document. Let associated element be document’s root element, if there is one, or null otherwise.
  14. Perform a scroll of scrolling box to position, associated element as the associated element and behavior as the scroll behavior.

To scroll an element element to x,y optionally with a scroll behavior behavior (which is "auto" if omitted) means to:

  1. Let box be element’s associated scrolling box.

  2. If box has rightward overflow direction
    Let x be max(0, min(x, element scrolling area width - element padding edge width)).
    If box has leftward overflow direction
    Let x be min(0, max(x, element padding edge width - element scrolling area width)).
  3. If box has downward overflow direction
    Let y be max(0, min(y, element scrolling area height - element padding edge height)).
    If box has upward overflow direction
    Let y be min(0, max(y, element padding edge height - element scrolling area height)).
  4. Let position be the scroll position box would have by aligning scrolling area x-coordinate x with the left of box and aligning scrolling area y-coordinate y with the top of box.

  5. If position is the same as box’s current scroll position, and box does not have an ongoing smooth scroll, abort these steps.

  6. Perform a scroll of box to position, element as the associated element and behavior as the scroll behavior.

7. Extensions to the HTMLElement Interface

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

HTMLElement/offsetParent

In all current engines.

Firefox1+Safari3+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5.5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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:

  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 and its computed value of the position property is fixed, 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 a containing block of absolutely-positioned descendants (regardless of whether there are any absolutely-positioned descendants).

      • It is the HTML 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.

    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.

HTMLElement/offsetTop

In all current engines.

Firefox1+Safari3+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5.5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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

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

  2. If the offsetParent of the element is null return the y-coordinate of the top border edge of the first CSS layout 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 result of subtracting the y-coordinate of the top padding edge of the first CSS layout box associated with the offsetParent of the element from the y-coordinate of the top border edge of the first CSS layout 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 CSS layout box considered.

HTMLElement/offsetLeft

In all current engines.

Firefox1+Safari3+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5.5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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

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

  2. If the offsetParent of the element is null return the x-coordinate of the left border edge of the first CSS layout 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 result of subtracting the x-coordinate of the left padding edge of the first CSS layout box associated with the offsetParent of the element from the x-coordinate of the left border edge of the first CSS layout box associated with the element, relative to the initial containing block origin, ignoring any transforms that apply to the element and its ancestors.

HTMLElement/offsetWidth

In all current engines.

Firefox1+Safari3+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5.5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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

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

  2. Return the border edge width of the first CSS layout box associated with the element, ignoring any transforms that apply to the element and its ancestors.

HTMLElement/offsetHeight

In all current engines.

Firefox1+Safari3+Chrome1+
Opera8+Edge79+
Edge (Legacy)12+IE5.5+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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

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

  2. Return the border edge height of the first CSS layout box associated with the element, ignoring any transforms that apply to the element and its ancestors.

8. Extensions to the HTMLImageElement Interface

partial interface HTMLImageElement {
  readonly attribute long x;
  readonly attribute long y;
};

HTMLImageElement/x

In all current engines.

Firefox14+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IENone
Firefox for Android14+iOS Safari1+Chrome for AndroidYesAndroid WebView1+Samsung InternetYesOpera Mobile12.1+

The x attribute, on getting, must return the x-coordinate of the left border edge of the first CSS layout box associated with the element, relative to the initial containing block origin, ignoring any transforms that apply to the element and its ancestors, or zero if there is no CSS layout box.

HTMLImageElement/y

In all current engines.

Firefox14+Safari3+Chrome1+
Opera12.1+Edge79+
Edge (Legacy)12+IENone
Firefox for Android14+iOS Safari1+Chrome for AndroidYesAndroid WebView1+Samsung InternetYesOpera Mobile12.1+

The y attribute, on getting, must return the y-coordinate of the top border edge of the first CSS layout box associated with the element, relative to the initial containing block origin, ignoring any transforms that apply to the element and its ancestors, or zero if there is no CSS layout box.

9. Extensions to the Range Interface

Range

In all current engines.

Firefox1+Safari1+Chrome1+
Opera9+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+
partial interface Range {
  DOMRectList getClientRects();
  [NewObject] DOMRect getBoundingClientRect();
};

Range/getClientRects

In all current engines.

Firefox4+Safari5+Chrome4+
Opera12.1+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari4+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile12.1+

The getClientRects() method, when invoked, must return an empty DOMRectList object if the range is not in the document and otherwise a DOMRectList object containing a list of DOMRect objects in content order that matches the following constraints:

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

Range/getBoundingClientRect

In all current engines.

Firefox4+Safari5+Chrome4+
Opera12.1+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari4+Chrome for Android18+Android WebView37+Samsung Internet1.0+Opera Mobile12.1+

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

  1. Let list be the result of invoking getClientRects() on the same range this method was invoked on.

  2. If list is empty return a DOMRect object whose x, y, width and height members are zero.

  3. If all rectangles in list have zero width or height, return the first rectangle in list.

  4. Otherwise, return a DOMRect object describing the smallest rectangle that includes all of the rectangles in list of which the height or width is not zero.

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

10. Extensions to the MouseEvent Interface

MouseEvent

In all current engines.

Firefox1+Safari3.1+Chrome1+
Opera10.6+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android4+iOS Safari2+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile11+

The object IDL fragment redefines some members. Can we resolve this somehow?

partial interface MouseEvent {
  readonly attribute double screenX;
  readonly attribute double screenY;
  readonly attribute double pageX;
  readonly attribute double pageY;
  readonly attribute double clientX;
  readonly attribute double clientY;
  readonly attribute double x;
  readonly attribute double y;
  readonly attribute double offsetX;
  readonly attribute double offsetY;
};

partial dictionary MouseEventInit {
  double screenX = 0.0;
  double screenY = 0.0;
  double clientX = 0.0;
  double clientY = 0.0;
};

The screenX attribute must return the x-coordinate of the position where the event occurred relative to the origin of the Web-exposed screen area.

The screenY attribute must return the y-coordinate of the position where the event occurred relative to the origin of the Web-exposed screen area.

MouseEvent/pageX

In all current engines.

FirefoxYesSafariYesChrome45+
OperaYesEdge79+
Edge (Legacy)12+IE9+
Firefox for AndroidYesiOS SafariYesChrome for Android45+Android WebView45+Samsung Internet5.0+Opera MobileYes

The pageX attribute must follow these steps:

  1. If the event’s dispatch flag is set, return the horizontal coordinate of the position where the event occurred relative to the origin of the initial containing block and terminate these steps.

  2. Let offset be the value of the scrollX attribute of the event’s associated Window object, if there is one, or zero otherwise.

  3. Return the sum of offset and the value of the event’s clientX attribute.

MouseEvent/pageY

In all current engines.

FirefoxYesSafariYesChrome45+
OperaYesEdge79+
Edge (Legacy)12+IE9+
Firefox for AndroidYesiOS SafariYesChrome for Android45+Android WebView45+Samsung Internet5.0+Opera MobileYes

The pageY attribute must follow these steps:

  1. If the event’s dispatch flag is set, return the vertical coordinate of the position where the event occurred relative to the origin of the initial containing block and terminate these steps.

  2. Let offset be the value of the scrollY attribute of the event’s associated Window object, if there is one, or zero otherwise.

  3. Return the sum of offset and the value of the event’s clientY attribute.

The clientX attribute must return the x-coordinate of the position where the event occurred relative to the origin of the viewport.

The clientY attribute must return the y-coordinate of the position where the event occurred relative to the origin of the viewport.

MouseEvent/x

In all current engines.

Firefox53+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+IE9+
Firefox for Android53+iOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes

The x attribute must return the value of clientX.

MouseEvent/y

In all current engines.

Firefox53+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+IE9+
Firefox for Android53+iOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes

The y attribute must return the value of clientY.

MouseEvent/offsetX

In all current engines.

Firefox39+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+IE9+
Firefox for Android43+iOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes

The offsetX attribute must follow these steps:

  1. If the event’s dispatch flag is set, return the x-coordinate of the position where the event occurred relative to the origin of the padding edge of the target node, ignoring the transforms that apply to the element and its ancestors, and terminate these steps.

  2. Return the value of the event’s pageX attribute.

MouseEvent/offsetY

In all current engines.

Firefox39+SafariYesChromeYes
OperaYesEdgeYes
Edge (Legacy)12+IE9+
Firefox for Android43+iOS SafariYesChrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes

The offsetY attribute must follow these steps:

  1. If the event’s dispatch flag is set, return the y-coordinate of the position where the event occurred relative to the origin of the padding edge of the target node, ignoring the transforms that apply to the element and its ancestors, and terminate these steps.

  2. Return the value of the event’s pageY attribute.

11. Geometry

11.1. The GeometryUtils Interface

enum CSSBoxType { "margin", "border", "padding", "content" };
dictionary BoxQuadOptions {
  CSSBoxType box = "border";
  GeometryNode relativeTo; // XXX default document (i.e. viewport)
};

dictionary ConvertCoordinateOptions {
  CSSBoxType fromBox = "border";
  CSSBoxType toBox = "border";
};

interface mixin GeometryUtils {
  sequence<DOMQuad> getBoxQuads(optional BoxQuadOptions options = {});
  DOMQuad convertQuadFromNode(DOMQuadInit quad, GeometryNode from, optional ConvertCoordinateOptions options = {});
  DOMQuad convertRectFromNode(DOMRectReadOnly rect, GeometryNode from, optional ConvertCoordinateOptions options = {});
  DOMPoint convertPointFromNode(DOMPointInit point, GeometryNode from, optional ConvertCoordinateOptions options = {}); // XXX z,w turns into 0
};

Text includes GeometryUtils; // like Range
Element includes GeometryUtils;
CSSPseudoElement includes GeometryUtils;
Document includes GeometryUtils;

typedef (Text or Element or CSSPseudoElement or Document) GeometryNode;

The getBoxQuads(options) method must run the following steps:

  1. DOM order

    p1 = top left even in RTL

    scale to 0 means divide by zero, return 0x0

    cross-frames not allowed, throw WrongDocumentError?

    points are flattened (3d transform), z=0. like getClientRect

    test block in inline

    pseudo-elements before/after are children of the element

    viewport boxes are all the same

The convertQuadFromNode(quad, from, options) method must run the following steps:

  1. ...

The convertRectFromNode(rect, from, options) method must run the following steps:

  1. ...

The convertPointFromNode(point, from, options) method must run the following steps:

  1. ...

12. Events

12.1. Resizing viewports

Window/resize_event

In all current engines.

Firefox1+Safari1.1+Chrome1+
Opera7+Edge79+
Edge (Legacy)12+IE4+
Firefox for Android4+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile10.1+

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

When asked to run the resize steps for a Document doc, run these steps:

  1. If doc’s viewport has had its width or height changed (e.g. as a result of the user resizing the browser window, or changing the page zoom scale factor, or an iframe element’s dimensions are changed) since the last time these steps were run, fire an event named resize at the Window object associated with doc.

12.2. Scrolling

Element/scroll_event

In all current engines.

FirefoxYesSafari1.3+ChromeYes
Opera?EdgeYes
Edge (Legacy)18IE?
Firefox for AndroidYesiOS Safari1+Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera Mobile?

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

Each Document has an associated list of pending scroll event targets, initially empty.

Whenever a viewport gets scrolled (whether in response to user interaction or by an API), the user agent must run these steps:

  1. Let doc be the viewport’s associated Document.

  2. If doc is already in doc’s pending scroll event targets, abort these steps.

  3. Append doc to doc’s pending scroll event targets.

Whenever an element gets scrolled (whether in response to user interaction or by an API), the user agent must run these steps:

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

  2. If the element is already in doc’s pending scroll event targets, abort these steps.

  3. Append the element to doc’s pending scroll event targets.

When asked to run the scroll steps for a Document doc, run these steps:

  1. For each item target in doc’s pending scroll event targets, in the order they were added to the list, run these substeps:

    1. If target is a Document, fire an event named scroll that bubbles at target.

    2. Otherwise, fire an event named scroll at target.

  2. Empty doc’s pending scroll event targets.

12.3. Event summary

This section is non-normative.

Event Interface Interesting targets Description

SVGElement/resize_event

FirefoxYesSafari?ChromeYes
OperaYesEdgeYes
Edge (Legacy)NoneIE?
Firefox for AndroidYesiOS Safari?Chrome for AndroidYesAndroid WebViewYesSamsung InternetYesOpera MobileYes
resize
Event Window Fired at the Window when the viewport is resized.

Document/scroll_event

In all current engines.

Firefox6+Safari2+Chrome1+
Opera11.6+Edge79+
Edge (Legacy)12+IE9+
Firefox for Android6+iOS Safari1+Chrome for Android18+Android WebView1+Samsung Internet1.0+Opera Mobile12+

SVGElement/scroll_event

In no current engines.

Firefox?Safari?Chrome?
Opera?Edge?
Edge (Legacy)?IE?
Firefox for Android?iOS Safari?Chrome for Android?Android WebView?Samsung Internet?Opera Mobile?
scroll
Event Document, elements Fired at the Document or element when the viewport or element is scrolled, respectively.

13. CSS properties

The features in this section should be moved to some other specification.

13.1. Smooth Scrolling: The scroll-behavior Property

scroll-behavior

In all current engines.

Firefox36+Safari🔰 14+Chrome61+
Opera48+Edge79+
Edge (Legacy)NoneIENone
Firefox for Android36+iOS Safari🔰 14+Chrome for Android61+Android WebView61+Samsung Internet8.0+Opera Mobile45+
Name: scroll-behavior
Value: auto | smooth
Initial: auto
Applies to: scrolling boxes
Inherited: no
Percentages: n/a
Computed value: specified value
Canonical order: per grammar
Animatable: no

The scroll-behavior property specifies the scrolling behavior for a scrolling box, when scrolling happens due to navigation, CSSOM scrolling APIs, or scroll snapping operations not initiated by the user [CSS-SCROLL-SNAP-1]. Any other scrolls, e.g. those that are performed by the user, are not affected by this property. When this property is specified on the root element, it applies to the viewport instead.

The scroll-behavior property of the HTML body element is not propagated to the viewport.

auto
The scrolling box is scrolled in an instant fashion.
smooth
The scrolling box is scrolled in a smooth fashion using a user-agent-defined timing function over a user-agent-defined period of time. User agents should follow platform conventions, if any.

User agents may ignore this property.

14. Security and Privacy Considerations

The Screen interface exposes information about the user’s display configuration, which maybe be used as input to fingerprinting algorithms. User agents may choose to hide or quantize information about the screen size or configuration, in order to protect the user’s privacy.

MouseEvent contains information about the screen-relative coordinates of the event. User agents may set these properties to values that obscure the actual screen-relative location of the event, in order to protect the user’s privacy.

15. Changes

This section documents some of the changes between publications of this specification. This section is not exhaustive. Bug fixes and editorial changes are generally not listed.

Changes From 19 October 2020

Changes From 31 January 2020

Changes From 17 December 2013 To 31 January 2020

Changes From 4 August 2011 To 17 December 2013

16. Acknowledgements

The editors would like to thank Alan Stearns, Alexey Feldgendler, Antonio Gomes, Björn Höhrmann, Boris Zbarsky, Chris Rebert, Corey Farwell, Dan Bates, David Vest, Elliott Sprehn, Garrett Smith, Henrik Andersson, Hallvord R. M. Steen, Kang-Hao Lu, Koji Ishii, Leif Arne Storset, Luiz Agostini, Maciej Stachowiak, Michael Dyck, Mike Wilson, Morten Stenshorne, Olli Pettay, Pavel Curtis, Peter-Paul Koch, Rachel Kmetz, Rick Byers, Robert O’Callahan, Sam Weinig, Scott Johnson, Sebastian Zartner, Stewart Brodie, Sylvain Galineau, Tab Atkins, Tarquin Wilton-Jones, Thomas Moore, Thomas Shinnick, and Xiaomei Ji for their contributions to this document.

Special thanks to the Microsoft employees who first implemented many of the features specified in this draft, which were first widely deployed by the Windows Internet Explorer browser.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Tests

Tests relating to the content of this specification may be documented in “Tests” blocks like this one. Any such block is non-normative.


Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-ALIGN-3]
Elika Etemad; Tab Atkins Jr.. CSS Box Alignment Module Level 3. 21 April 2020. WD. URL: https://www.w3.org/TR/css-align-3/
[CSS-BACKGROUNDS-3]
Bert Bos; Elika Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. 22 December 2020. CR. URL: https://www.w3.org/TR/css-backgrounds-3/
[CSS-BREAK-4]
Rossen Atanassov; Elika Etemad. CSS Fragmentation Module Level 4. 18 December 2018. WD. URL: https://www.w3.org/TR/css-break-4/
[CSS-DEVICE-ADAPT]
Rune Lillesveen; Florian Rivoal; Matt Rakow. CSS Device Adaptation Module Level 1. 29 March 2016. WD. URL: https://www.w3.org/TR/css-device-adapt-1/
[CSS-DISPLAY-3]
Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. 18 December 2020. CR. URL: https://www.w3.org/TR/css-display-3/
[CSS-OVERFLOW-3]
David Baron; Elika Etemad; Florian Rivoal. CSS Overflow Module Level 3. 3 June 2020. WD. URL: https://www.w3.org/TR/css-overflow-3/
[CSS-POSITION-3]
Elika Etemad; et al. CSS Positioned Layout Module Level 3. 19 May 2020. WD. URL: https://www.w3.org/TR/css-position-3/
[CSS-PSEUDO-4]
Daniel Glazman; Elika Etemad; Alan Stearns. CSS Pseudo-Elements Module Level 4. 31 December 2020. WD. URL: https://www.w3.org/TR/css-pseudo-4/
[CSS-SCOPING-1]
Tab Atkins Jr.; Elika Etemad. CSS Scoping Module Level 1. 3 April 2014. WD. URL: https://www.w3.org/TR/css-scoping-1/
[CSS-SCROLL-SNAP-1]
Matt Rakow; et al. CSS Scroll Snap Module Level 1. 11 March 2021. CR. URL: https://www.w3.org/TR/css-scroll-snap-1/
[CSS-TEXT-3]
Elika Etemad; Koji Ishii; Florian Rivoal. CSS Text Module Level 3. 22 April 2021. CR. URL: https://www.w3.org/TR/css-text-3/
[CSS-TRANSFORMS-1]
Simon Fraser; et al. CSS Transforms Module Level 1. 14 February 2019. CR. URL: https://www.w3.org/TR/css-transforms-1/
[CSS-VALUES]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 3. 6 June 2019. CR. URL: https://www.w3.org/TR/css-values-3/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 11 November 2020. WD. URL: https://www.w3.org/TR/css-values-4/
[CSS-WRITING-MODES-4]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 4. 30 July 2019. CR. URL: https://www.w3.org/TR/css-writing-modes-4/
[CSS3-BOX]
Elika Etemad. CSS Box Model Module Level 3. 22 December 2020. CR. URL: https://www.w3.org/TR/css-box-3/
[CSSOM]
Simon Pieters; Glenn Adams. CSS Object Model (CSSOM). 17 March 2016. WD. URL: https://www.w3.org/TR/cssom-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[GEOMETRY-1]
Simon Pieters; Chris Harrelson. Geometry Interfaces Module Level 1. 4 December 2018. CR. URL: https://www.w3.org/TR/geometry-1/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SVG11]
Erik Dahlström; et al. Scalable Vector Graphics (SVG) 1.1 (Second Edition). 16 August 2011. REC. URL: https://www.w3.org/TR/SVG11/
[UIEVENTS]
Gary Kacmarcik; Travis Leithead; Doug Schepers. UI Events. 30 May 2019. WD. URL: https://www.w3.org/TR/uievents/
[WEBIDL]
Boris Zbarsky. Web IDL. 15 December 2016. ED. URL: https://heycam.github.io/webidl/

Informative References

[SVG2]
Amelia Bellamy-Royds; et al. Scalable Vector Graphics (SVG) 2. 4 October 2018. CR. URL: https://www.w3.org/TR/SVG2/

Property Index

Name Value Initial Applies to Inh. %ages Ani­mat­able Canonical order Com­puted value
scroll-behavior auto | smooth auto scrolling boxes no n/a no per grammar specified value

IDL Index

enum ScrollBehavior { "auto", "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;

    // 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;
    undefined scroll(optional ScrollToOptions options = {});
    undefined scroll(unrestricted double x, unrestricted double y);
    undefined scrollTo(optional ScrollToOptions options = {});
    undefined scrollTo(unrestricted double x, unrestricted double y);
    undefined scrollBy(optional ScrollToOptions options = {});
    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;
};

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

[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;
};

[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;
};

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

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

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

partial interface Element {
  DOMRectList getClientRects();
  [NewObject] DOMRect getBoundingClientRect();
  undefined scrollIntoView(optional (boolean or ScrollIntoViewOptions) arg = {});
  undefined scroll(optional ScrollToOptions options = {});
  undefined scroll(unrestricted double x, unrestricted double y);
  undefined scrollTo(optional ScrollToOptions options = {});
  undefined scrollTo(unrestricted double x, unrestricted double y);
  undefined scrollBy(optional ScrollToOptions options = {});
  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;
};

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

partial interface HTMLImageElement {
  readonly attribute long x;
  readonly attribute long y;
};

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

partial interface MouseEvent {
  readonly attribute double screenX;
  readonly attribute double screenY;
  readonly attribute double pageX;
  readonly attribute double pageY;
  readonly attribute double clientX;
  readonly attribute double clientY;
  readonly attribute double x;
  readonly attribute double y;
  readonly attribute double offsetX;
  readonly attribute double offsetY;
};

partial dictionary MouseEventInit {
  double screenX = 0.0;
  double screenY = 0.0;
  double clientX = 0.0;
  double clientY = 0.0;
};

enum CSSBoxType { "margin", "border", "padding", "content" };
dictionary BoxQuadOptions {
  CSSBoxType box = "border";
  GeometryNode relativeTo; // XXX default document (i.e. viewport)
};

dictionary ConvertCoordinateOptions {
  CSSBoxType fromBox = "border";
  CSSBoxType toBox = "border";
};

interface mixin GeometryUtils {
  sequence<DOMQuad> getBoxQuads(optional BoxQuadOptions options = {});
  DOMQuad convertQuadFromNode(DOMQuadInit quad, GeometryNode from, optional ConvertCoordinateOptions options = {});
  DOMQuad convertRectFromNode(DOMRectReadOnly rect, GeometryNode from, optional ConvertCoordinateOptions options = {});
  DOMPoint convertPointFromNode(DOMPointInit point, GeometryNode from, optional ConvertCoordinateOptions options = {}); // XXX z,w turns into 0
};

Text includes GeometryUtils; // like Range
Element includes GeometryUtils;
CSSPseudoElement includes GeometryUtils;
Document includes GeometryUtils;

typedef (Text or Element or CSSPseudoElement or Document) GeometryNode;

Issues Index

The terms CSS layout box and SVG layout box are not currently defined by CSS or SVG.
The object IDL fragment redefines some members. Can we resolve this somehow?
DOM order

p1 = top left even in RTL

scale to 0 means divide by zero, return 0x0

cross-frames not allowed, throw WrongDocumentError?

points are flattened (3d transform), z=0. like getClientRect

test block in inline

pseudo-elements before/after are children of the element

viewport boxes are all the same

...
...
...
The features in this section should be moved to some other specification.