Title: CSSOM View Module ED: https://drafts.csswg.org/cssom-view/ TR: https://www.w3.org/TR/cssom-view-1/ Previous Version: https://www.w3.org/TR/2016/WD-cssom-view-1-20160317/ Previous Version: https://www.w3.org/TR/2013/WD-cssom-view-20131217/ Previous Version: https://www.w3.org/TR/2011/WD-cssom-view-20110804/ Previous Version: https://www.w3.org/TR/2009/WD-cssom-view-20090804/ Previous Version: https://www.w3.org/TR/2008/WD-cssom-view-20080222/ Previous Version: https://www.w3.org/TR/2000/REC-DOM-Level-2-Style-20001113/ Group: CSSWG Status: ED Work Status: Revising Shortname: cssom-view Level: 1 Editor: Simon Fraser, Apple Inc http://www.apple.com/, simon.fraser@apple.com, w3cid 44066 Editor: Emilio Cobos Álvarez 106537, Mozilla https://mozilla.org, emilio@mozilla.com Former Editor: Simon Pieters, Opera Software AS http://www.opera.com, simonp@opera.com Former Editor: Glenn Adams, Cox Communications, Inc. http://www.cox.com, glenn.adams@cos.com, http://www.w3.org/wiki/User:Gadams Former Editor: Anne van Kesteren, Opera Software ASA http://www.opera.com, annevk@annevk.nl, https://annevankesteren.nl/ !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. Ignored Vars: rect, point, quad Include Can I Use Panels: true Can I Use URL: https://drafts.csswg.org/cssom-view/ Can I Use URL: https://www.w3.org/TR/cssom-view-1/
spec:css-ui-4; type:property; text:pointer-events
spec:css2; type:dfn; text:canvas
spec:css2; type:dfn; text:viewport
spec:html; type:dfn;
text: inert
text: the body element
text: rules for parsing integers
body element) is
potentially scrollable if all of the following conditions are true:
* body has an associated [=CSS/box=].
* body's parent element's computed value of the 'overflow-x' or 'overflow-y' properties is neither ''overflow/visible'' nor ''overflow/clip''.
* body's computed value of the 'overflow-x' or 'overflow-y' properties is neither ''overflow/visible'' nor ''overflow/clip''.
Note: A <{body}> element that is potentially scrollable might not have a scrolling box.
For instance, it could have a used value of 'overflow' being ''overflow/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-align-3#overflow-scroll-position]].
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 |
|
|
| leftward and downward |
|
|
| leftward and upward |
|
|
| rightward and upward |
|
|
This animation shows an example of a zoomed in visual viewport being "panned" around (for example, by a user performing a touch drag). The page is scaled so that the layout viewport is larger than the visual viewport.
A scroll delta is applied to the visual viewport first. When the visual viewport is at its extent, scroll delta will be applied to the layout viewport. This behavior is implemented by the [=viewport/perform a scroll=] steps.
auto" if omitted),
the following steps must be run:
auto" and element is not null and its computed value of the
'scroll-behavior' property is ''scroll-behavior/smooth''
smooth
behavior: "instant" always performs an instant scroll by this algorithm.
Note: If the scroll position did not change as a result of the user interaction or programmatic invocation, where no translations were applied as a result, then no scrollend event fires because no scrolling occurred.
auto" if omitted) it must perform a coordinated viewport scroll by following these steps:
1. Let doc be the viewport's associated {{Document}}.
1. Let vv be the {{VisualViewport}} whose associated document is doc.
1. Let maxX be the difference between viewport's scrolling box's width and the value of vv's width attribute.
1. Let maxY be the difference between viewport's scrolling box's height and the value of vv's height attribute.
1. Let dx be the horizontal component of position - the value vv's pageLeft attribute
1. Let dy be the vertical component of position - the value of vv's pageTop attribute
1. Let visual x be the value of vv's offsetLeft attribute.
1. Let visual y be the value of vv's offsetTop attribute.
1. Let visual dx be min(maxX, max(0, visual x + dx)) - visual x.
1. Let visual dy be min(maxY, max(0, visual y + dy)) - visual y.
1. Let layout dx be dx - visual dx
1. Let layout dy be dy - visual dy
1. Let element be doc's root element if there is one, null otherwise.
1. Perform a scroll of the viewport's scrolling box to its current scroll position + (layout dx, layout dy) with element as the
associated element, and behavior as the scroll behavior.
1. Perform a scroll of vv's scrolling box to its current scroll position + (visual dx, visual dy) with element as the associated
element, and behavior as the scroll behavior.
Note: Conceptually, the visual viewport is scrolled until it "bumps up" against the layout viewport
edge and then "pushes" the layout viewport by applying the scroll delta to the layout viewport.
However, the scrolls in the steps above are computed ahead of time and applied in the opposite order
so that the layout viewport is scrolled before the visual viewport. This is done for historical
reasons to ensure consistent scroll event ordering. See the example
above for a visual depiction.
#top fragment identifier, as defined in HTML. [[!HTML]]
Infinity, -Infinity or NaN),
then x must be changed to the value 0. [[!WEBIDL]]
enum ScrollBehavior { "auto", "instant", "smooth" };
dictionary ScrollOptions {
ScrollBehavior behavior = "auto";
};
dictionary ScrollToOptions : ScrollOptions {
unrestricted double left;
unrestricted double top;
};
partial interface Window {
[NewObject] MediaQueryList matchMedia(CSSOMString query);
[SameObject, Replaceable] readonly attribute Screen screen;
[SameObject, Replaceable] readonly attribute VisualViewport? visualViewport;
// browsing context
undefined moveTo(long x, long y);
undefined moveBy(long x, long y);
undefined resizeTo(long width, long height);
undefined resizeBy(long x, long y);
// viewport
[Replaceable] readonly attribute long innerWidth;
[Replaceable] readonly attribute long innerHeight;
// viewport scrolling
[Replaceable] readonly attribute double scrollX;
[Replaceable] readonly attribute double pageXOffset;
[Replaceable] readonly attribute double scrollY;
[Replaceable] readonly attribute double pageYOffset;
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;
};
When the matchMedia(query) method is invoked these steps must be run:
Document
as the document,
with parsed media query list as its associated [=MediaQueryList/media query list=].
var viewportWidth = innerWidth
open() feature name is one of the following:
function handleOrientationChange(event) {
if(event.matches) // landscape
…
else
…
}
var mql = matchMedia("(orientation:landscape)");
mql.onchange = handleOrientationChange;
[Exposed=Window]
interface MediaQueryList : EventTarget {
readonly attribute CSSOMString media;
readonly attribute boolean matches;
undefined addListener(EventListener? callback);
undefined removeListener(EventListener? callback);
attribute EventHandler onchange;
};
The media attribute must return
the associated media.
The matches attribute must return
the associated matches state.
The addListener(callback) method,
when invoked, must run these steps:
1. Add an event listener with [=this=]
and an event listener whose
type is change,
and callback is |callback|.
The removeListener(callback) method,
when invoked, must run these steps:
1. If [=this=]’s event listener list
contains an event listener whose
type is change,
callback is |callback|,
and capture is false,
then remove an event listener with
[=this=] and that event listener.
Note: This specification initially had a custom callback mechanism with {{addListener()}} and
{{removeListener()}}, and the callback was invoked with the associated media query list as argument.
Now the normal event mechanism is used instead.
For backwards compatibility, the {{addListener()}} and {{removeListener()}} methods
are basically aliases for {{addEventListener()}} and {{removeEventListener()}}, respectively,
and the change event masquerades as a {{MediaQueryList}}.
The following are the event handlers
(and their corresponding event handler event types) that must be supported,
as event handler IDL attributes, by all objects implementing the {{MediaQueryList}} interface:
| Event handler | Event handler event type |
|---|---|
| onchange | change |
[Exposed=Window]
interface MediaQueryListEvent : Event {
constructor(CSSOMString type, optional MediaQueryListEventInit eventInitDict = {});
readonly attribute CSSOMString media;
readonly attribute boolean matches;
};
dictionary MediaQueryListEventInit : EventInit {
CSSOMString media = "";
boolean matches = false;
};
The media attribute must return the value it was initialized to.
The matches attribute must return the value it was initialized to.
| Event | Interface | Interesting targets | Description |
|---|---|---|---|
| change | {{MediaQueryListEvent}} | {{MediaQueryList}} | Fired at the {{MediaQueryList}} when the matches state changes. |
[Exposed=Window]
interface Screen {
readonly attribute long availWidth;
readonly attribute long availHeight;
readonly attribute long width;
readonly attribute long height;
readonly attribute unsigned long colorDepth;
readonly attribute unsigned long pixelDepth;
};
The availWidth attribute must return the width of the Web-exposed
available screen area.
The availHeight attribute must return the height of the
Web-exposed available screen area.
The width attribute must return the width of the Web-exposed
screen area.
The height attribute must return the height of the Web-exposed
screen area.
The colorDepth and pixelDepth attributes should return the number of bits
allocated to colors for a pixel in the output device, excluding the alpha
channel. If the user agent is not able to return the number of bits used by the
output device, it should return the closest estimation such as, for example, the
number of bits used by the frame buffer sent to the display or any internal
representation that would be the closest to the value the output device would
use. The user agent must return a value for these attributes at least equal to
the value of the '@media/color' media feature multiplied by three. If the different
color components are not represented with the same number of bits, the returned
value may be greater than three times the value of the '@media/color' media feature. If the user
agent does not know the color depth or does not want to return it for privacy
considerations, it should return 24.
Note: The {{colorDepth}} and {{pixelDepth}} attributes return the same value for
compatibility reasons.
Note: Some non-conforming implementations are known to return 32 instead of 24.
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;
};
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.
1. If there is a [=CSS/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.
1. If the document has a [=root element=], return the [=root element=] and terminate these steps.
1. Return null.
Note: The {{elementFromPoint()}} method does not necessarily return the top-most painted element. For
instance, an element can be excluded from being a target for hit testing by using the 'pointer-events' CSS property.
The elementsFromPoint(x, y) method must follow these steps: 1. Let sequence be a new empty sequence. 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 sequence and terminate these steps. 1. For each [=CSS/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. 1. If the document has a [=root element=], and the last item in sequence is not the [=root element=], append the [=root element=] to sequence. 1. Return sequence. 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. 1. 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. 1. 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. 1. 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:
The scrollingElement attribute, on getting, must run these steps:
1. If the {{Document}} is in quirks mode, follow these substeps:
1. If the body element exists, and it is not potentially scrollable, return the body element and abort these steps.
For this purpose,
a value of ''overflow:clip'' on the the body element's parent element
must be treated as ''overflow:hidden''.
1. Return null and abort these steps.
1. If there is a [=root element=], return the [=root element=] and abort these steps.
1. Return null.
Note: For non-conforming user agents that always use the quirks mode behavior for {{Element/scrollTop}}
and {{Element/scrollLeft}}, the {{Document/scrollingElement}} attribute is expected to also always return
the body element (or null if it does not exist).
This API exists so that Web developers can use it to get the right element to use for scrolling APIs,
without making assumptions about a particular user agent's behavior
or having to invoke a scroll to see which element scrolls the viewport.
Note: the body element is different from HTML's document.body
in that the latter can return a frameset element.
[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 {{Range/getClientRects()}} method on the range.
1. If list is empty, return null.
1. Return the {{DOMRect}} object in list at index 0.
1. If caret node is a text entry widget that is a replaced element,
and that is in the document,
return a [=scaled=] {{DOMRect}} object for the caret in the widget
as represented by the caret offset value.
The transforms that apply to the element and its ancestors are applied.
1. Return null.
Note: This {{DOMRect}} object is not live.
enum ScrollLogicalPosition { "start", "center", "end", "nearest" };
dictionary ScrollIntoViewOptions : ScrollOptions {
ScrollLogicalPosition block = "start";
ScrollLogicalPosition inline = "nearest";
};
dictionary CheckVisibilityOptions {
boolean checkOpacity = false;
boolean checkVisibilityCSS = false;
boolean contentVisibilityAuto = false;
boolean opacityProperty = false;
boolean visibilityProperty = false;
};
partial interface Element {
DOMRectList getClientRects();
[NewObject] DOMRect getBoundingClientRect();
boolean checkVisibility(optional CheckVisibilityOptions options = {});
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;
readonly attribute double currentCSSZoom;
};
Note: The {{CheckVisibilityOptions/checkOpacity}} and {{CheckVisibilityOptions/checkVisibilityCSS}} properties are historical names.
These properties have aliases that match the new naming scheme,
namely {{CheckVisibilityOptions/opacityProperty}} and {{CheckVisibilityOptions/visibilityProperty}}.
The getClientRects() method, when invoked, must return the result of the following algorithm:
1. If the element on which it was invoked does not have an associated [=CSS/box=] return an empty {{DOMRectList}} object and stop this algorithm.
1. If the element has an associated SVG layout box return a [=scaled=] {{DOMRectList}} object containing a single {{DOMRect}} object that describes the bounding box of the element as defined by the SVG specification, applying the transforms that apply to the element and its ancestors.
1. 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 {{Element/getClientRects()}} are not live.
The getBoundingClientRect() method, when
invoked on an element element, must return the result of
getting the bounding box for element.
div element in a document:
var example = document.getElementsByTagName("div")[0].getBoundingClientRect();
var exampleWidth = example.width;
var exampleHeight = example.height;
auto".
1. Let block be "start".
1. Let inline be "nearest".
1. If arg is a {{ScrollIntoViewOptions}} dictionary, then:
1. Set behavior to the {{ScrollOptions/behavior}} dictionary member of options.
1. Set block to the {{ScrollIntoViewOptions/block}} dictionary member of options.
1. Set inline to the {{ScrollIntoViewOptions/inline}} dictionary member of options.
1. Otherwise, if arg is false, then set block to "end".
1. If the element does not have any associated [=CSS/box=],
or is not available to user-agent features,
then return.
1. Scroll the element into view
with behavior, block, and inline.
1. 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.
1. Normalize non-finite values for {{ScrollToOptions/left}} and {{ScrollToOptions/top}} dictionary members of options, if present.
1. Let x be the value of the {{ScrollToOptions/left}} dictionary member of options, if present, or the element's current scroll position on the x axis otherwise.
1. Let y be the value of the {{ScrollToOptions/top}} dictionary member of options, if present, or the element's current scroll position on the y axis otherwise.
1. If invoked with two arguments, follow these substeps:
1. Let options be null converted to a {{ScrollToOptions}} dictionary. [[!WEBIDL]]
1. Let x and y be the arguments, respectively.
1. Normalize non-finite values for x and y.
1. Let the {{ScrollToOptions/left}} dictionary member of options have the value x.
1. Let the {{ScrollToOptions/top}} dictionary member of options have the value y.
1. Let document be the element's node document.
1. If document is not the active document, terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, terminate these steps.
1. If the element is the [=root element=] and document is in quirks mode, terminate these steps.
1. If the element is the [=root element=] invoke {{Window/scroll()}} on window with {{Window/scrollX}} on window as first argument and y as second argument,
and terminate these steps.
1. If the element is the body element,
document is in quirks mode,
and the element is not potentially scrollable,
invoke {{Window/scroll()}} on window with options as the only argument,
and terminate these steps.
1. If the element does not have any associated [=CSS/box=],
the element has no associated scrolling box,
or the element has no overflow,
terminate these steps.
1. Scroll the element to x,y,
with the scroll behavior being the value of the {{ScrollOptions/behavior}} dictionary member of options.
When the scrollTo() method is invoked, the
user agent must act as if the {{Element/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.
1. Normalize non-finite values for {{ScrollToOptions/left}} and {{ScrollToOptions/top}} dictionary members of options, if present.
1. If invoked with two arguments, follow these substeps:
1. Let options be null converted to a {{ScrollToOptions}} dictionary. [[!WEBIDL]]
1. Let x and y be the arguments, respectively.
1. Normalize non-finite values for x and y.
1. Let the {{ScrollToOptions/left}} dictionary member of options have the value x.
1. Let the {{ScrollToOptions/top}} dictionary member of options have the value y.
1. Add the value of {{Element/scrollLeft}} to the {{ScrollToOptions/left}} dictionary member.
1. Add the value of {{Element/scrollTop}} to the {{ScrollToOptions/top}} dictionary member.
1. Act as if the {{Element/scroll()}} method was invoked with options as the only argument.
The scrollTop attribute, on getting, must return the result of running these steps:
1. Let document be the element's node document.
1. If document is not the active document, return zero and terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, return zero and terminate these steps.
1. If the element is the [=root element=] and document is in quirks mode, return zero and terminate these steps.
1. If the element is the [=root element=] return the value of {{Window/scrollY}} on window.
1. If the element is the body element, document is in quirks mode, and the element is not potentially scrollable, return the value of {{Window/scrollY}} on window.
1. If the element does not have any associated [=CSS/box=], return zero and terminate these steps.
1. 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 {{Element/scrollTop}} attribute these steps must be run:
1. Let y be the given value.
1. Normalize non-finite values for y.
1. Let document be the element's node document.
1. If document is not the active document, terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, terminate these steps.
1. If the element is the [=root element=] and document is in quirks mode, terminate these steps.
1. If the element is the [=root element=] invoke {{Window/scroll()}} on window with {{Window/scrollX}} on window as first argument and y as second argument, and terminate these steps.
1. If the element is the body element, document is in quirks mode, and the element is not potentially scrollable, invoke {{Window/scroll()}} on window with {{Window/scrollX}} as first argument and y as second argument, and terminate these steps.
1. If the element does not have any associated [=CSS/box=], the element has no associated scrolling box, or the element has no overflow, terminate these steps.
1. Scroll the element to {{Element/scrollLeft}},y, with the scroll behavior being "auto".
The scrollLeft attribute, on getting, must return the result of running these steps:
1. Let document be the element's node document.
1. If document is not the active document, return zero and terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, return zero and terminate these steps.
1. If the element is the [=root element=] and document is in quirks mode, return zero and terminate these steps.
1. If the element is the [=root element=] return the value of {{Window/scrollX}} on window.
1. If the element is the body element, document is in quirks mode, and the element is not potentially scrollable, return the value of {{Window/scrollX}} on window.
1. If the element does not have any associated [=CSS/box=], return zero and terminate these steps.
1. 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 {{Element/scrollLeft}} attribute these steps must be run:
1. Let x be the given value.
1. Normalize non-finite values for x.
1. Let document be the element's node document.
1. If document is not the active document, terminate these steps.
1. Let window be the value of document's {{Document/defaultView}} attribute.
1. If window is null, terminate these steps.
1. If the element is the [=root element=] and document is in quirks mode, terminate these steps.
1. If the element is the [=root element=] invoke {{Window/scroll()}} on window with x as first argument and {{Window/scrollY}} on window as second argument, and terminate these steps.
1. If the element is the body element, document is in quirks mode, and the element is not potentially scrollable, invoke {{Window/scroll()}} on window with x as first argument and {{Window/scrollY}} on window as second argument, and terminate these steps.
1. If the element does not have any associated [=CSS/box=], the element has no associated scrolling box, or the element has no overflow, terminate these steps.
1. Scroll the element to x,{{Element/scrollTop}}, with the scroll behavior being "auto".
The scrollWidth attribute must return the result of running these steps:
1. Let document be the element's node document.
1. If document is not the active document, return zero and terminate these steps.
1. 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.
1. If the element is the [=root element=] and document is not in quirks mode return max(viewport scrolling area width, viewport width).
1. If the element is the body element, document is in quirks mode and the element is not potentially scrollable, return max(viewport scrolling area width, viewport width).
1. If the element does not have any associated [=CSS/box=] return zero and terminate these steps.
1. Return the width of the element's scrolling area.
The scrollHeight attribute must return the result of running these steps:
1. Let document be the element's node document.
1. If document is not the active document, return zero and terminate these steps.
1. 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.
1. If the element is the [=root element=] and document is not in quirks mode return max(viewport scrolling area height, viewport height).
1. If the element is the body element, document is in quirks mode and the element is not potentially scrollable, return max(viewport scrolling area height, viewport height).
1. If the element does not have any associated [=CSS/box=] return zero and terminate these steps.
1. Return the height of the element's scrolling area.
The clientTop attribute must run these steps:
1. If the element has no associated [=CSS/box=] or if the [=CSS/box=] is inline, return zero.
1. Return the [=unscaled=] computed value of the 'border-top-width' property plus the height of any scrollbar rendered between the top padding edge and the top border edge, ignoring any transforms that apply to the element and its ancestors.
The clientLeft attribute must run these steps:
1. If the element has no associated [=CSS/box=] or if the [=CSS/box=] is inline, return zero.
1. Return the [=unscaled=] computed value of the 'border-left-width' property plus the width of any scrollbar rendered between the left padding edge and the left border edge, ignoring any transforms that apply to the element and its ancestors.
The clientWidth attribute must run these steps:
1. If the element has no associated [=CSS/box=] or if the [=CSS/box=] is inline, return zero.
1. If the element is the [=root element=] and the element's node document is not in quirks mode, or if the element is the body element and the element's node document is in quirks mode, return the viewport width excluding the size of a rendered scroll bar (if any).
1. Return the [=unscaled=] width of the padding edge excluding the width of any rendered scrollbar between the padding edge and the border edge, ignoring any transforms or that apply to the element and its ancestors.
The clientHeight attribute must run these steps:
1. If the element has no associated [=CSS/box=] or if the [=CSS/box=] is inline, return zero.
1. If the element is the [=root element=] and the element's node document is not in quirks mode, or if the element is the body element and the element's node document is in quirks mode, return the viewport height excluding the size of a rendered scroll bar (if any).
1. Return the [=unscaled=] height of the padding edge excluding the height of any rendered scrollbar between the padding edge and the border edge, ignoring any transforms that apply to the element and its ancestors.
The currentCSSZoom attribute must return the
[=effective zoom=] of the element, or 1.0 if the element isn't [=rendered=].
start", then align element edge A with scrolling box edge A.
1. Otherwise, if block is "end", then align element edge B with scrolling box edge B.
1. Otherwise, if block is "center", then align the center of target bounding border box with the center of scrolling box in scrolling box's block flow direction.
1. Otherwise, block is "nearest":
start", then align element edge C with scrolling box edge C.
1. Otherwise, if inline is "end", then align element edge D with scrolling box edge D.
1. Otherwise, if inline is "center", then align the center of target bounding border box with the center of scrolling box in scrolling box's inline base direction.
1. Otherwise, inline is "nearest":
auto" if omitted) means to:
1. Let box be element's associated scrolling box.
1.
partial interface HTMLElement {
readonly attribute Element? offsetParent;
readonly attribute long offsetTop;
readonly attribute long offsetLeft;
readonly attribute long offsetWidth;
readonly attribute long offsetHeight;
};
The offsetParent attribute must return the result of running these steps:
1. If any of the following holds true return null and terminate this algorithm:
* The element does not have an associated [=CSS/box=].
* The element is the [=root element=].
* The element is the body element.
* The element's computed value of the 'position' property is ''position/fixed''.
1. 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 ''position/fixed'', terminate this algorithm and return null.
1. 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).
* The element has a non-default used value of 'zoom'.
* It is the body element.
* The computed value of the 'position' property of the element is ''static'' and the ancestor is one of the following HTML elements: td, th, or table.
1. If there is no more parent of ancestor in the flat tree, terminate this algorithm and return null.
1. Let ancestor be the parent of ancestor in the flat tree.
The offsetTop attribute must return the result of running these steps:
1. If the element is the body element or does not have any associated [=CSS/box=] return zero and terminate this algorithm.
1. If the {{HTMLElement/offsetParent}} of the element is null return the [=unscaled=] y-coordinate of the top border edge of the first [=CSS/box=] associated with the element, relative to the initial containing block origin, ignoring any transformsthat apply to the element and its ancestors and terminate this algorithm.
1. Return the [=unscaled=] result of subtracting the y-coordinate of the top padding edge
of the first [=CSS/box=] associated with the {{HTMLElement/offsetParent}} of the element
from the y-coordinate of the top border edge
of the first [=CSS/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/box=] considered.
The offsetLeft attribute must return the result of running these steps:
1. If the element is the body element or does not have any associated [=CSS/box=] return zero and terminate this algorithm.
1. If the {{HTMLElement/offsetParent}} of the element is null return the [=unscaled=] x-coordinate of the left border edge of the first [=CSS/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.
1. Return the [=unscaled=] result of subtracting the x-coordinate of the left padding edge of the first [=CSS/box=] associated with the {{HTMLElement/offsetParent}} of the element from the x-coordinate of the left border edge of the first [=CSS/box=] associated with the element, relative to the initial containing block origin, ignoring any transforms that apply to the element and its ancestors.
The offsetWidth attribute must return the result of running these steps:
1. If the element does not have any associated [=CSS/box=] return zero and terminate this algorithm.
1. Return the [=unscaled=] width of the axis-aligned bounding box
of the [=border boxes=]
of all fragments generated by the element's [=principal box=],
ignoring any transforms that apply to the element and its ancestors.
If the element's [=principal box=] is an [=inline-level box=]
which was "split" by a [=block-level=] descendant,
also include fragments generated by the [=block-level=] descendants,
unless they are zero width or height.
The offsetHeight attribute must return the result of running these steps:
1. If the element does not have any associated [=CSS/box=] return zero and terminate this algorithm.
1. Return the [=unscaled=] height of the axis-aligned bounding box
of the [=border boxes=]
of all fragments generated by the element's [=principal box=],
ignoring any transforms that apply to the element and its ancestors.
If the element's [=principal box=] is an [=inline-level box=]
which was "split" by a [=block-level=] descendant,
also include fragments generated by the [=block-level=] descendants,
unless they are zero width or height.
partial interface HTMLImageElement {
readonly attribute long x;
readonly attribute long y;
};
The x attribute, on getting, must return the [=scaled=] x-coordinate of the left border edge of the
first [=CSS/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/box=].
The y attribute, on getting, must return the [=scaled=] y-coordinate of the top border edge of the
first [=CSS/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/box=].
partial interface Range {
DOMRectList getClientRects();
[NewObject] DOMRect getBoundingClientRect();
};
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:
* For each element selected by the range, whose parent is not selected by the range, include the border areas returned by invoking {{Element/getClientRects()}} on the element.
* For each {{Text}} node selected or partially selected by the range (including when the
boundary-points are identical), include [=scaled=] {{DOMRect}} object (for the part that is selected, not
the whole line box). The bounds of these {{DOMRect}} objects are computed using font metrics;
thus, for horizontal writing, the vertical dimension of each box is determined by the font
ascent and descent, and the horizontal dimension by the text advance width. If the range covers
a partial typographic character unit (e.g. half a surrogate pair or part of
a grapheme cluster), the full typographic character unit must be included
for the purpose of computing the bounds of the relevant {{DOMRect}}. [[!CSS-TEXT-3]] The
transforms that apply to the ancestors are applied.
Note: The {{DOMRect}} objects returned by {{Range/getClientRects()}} are not live.
The getBoundingClientRect() method, when invoked, must return the result of the following
algorithm:
1. Let list be the result of invoking {{Range/getClientRects()}} on the same range this method was invoked on.
1. If list is empty return a {{DOMRect}} object whose {{DOMRect/x}}, {{DOMRect/y}}, {{DOMRect/width}} and {{DOMRect/height}} members are zero.
1. If all rectangles in list have zero width or height, return the first rectangle in
list.
1. 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 {{Range/getBoundingClientRect()}} is not live.
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.
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.
1. Let offset be the value of the {{Window/scrollX}} attribute of the event's associated {{Window}} object, if there is one, or zero otherwise.
1. Return the sum of offset and the value of the event's {{MouseEvent/clientX}} attribute.
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.
1. Let offset be the value of the {{Window/scrollY}} attribute of the event's associated {{Window}} object, if there is one, or zero otherwise.
1. Return the sum of offset and the value of the event's {{MouseEvent/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.
The x attribute must return the value of {{MouseEvent/clientX}}.
The y attribute must return the value of {{MouseEvent/clientY}}.
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.
1. Return the value of the event's {{MouseEvent/pageX}} attribute.
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.
1. Return the value of the event's {{MouseEvent/pageY}} attribute.
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:
...
...
...
[Exposed=Window]
interface VisualViewport : EventTarget {
readonly attribute double offsetLeft;
readonly attribute double offsetTop;
readonly attribute double pageLeft;
readonly attribute double pageTop;
readonly attribute double width;
readonly attribute double height;
readonly attribute double scale;
attribute EventHandler onresize;
attribute EventHandler onscroll;
attribute EventHandler onscrollend;
};
The offsetLeft attribute must run these steps:
1. If the visual viewport's associated document is not fully active, return 0.
1. Otherwise, return the offset of the left edge of the visual viewport from the left edge
of the layout viewport.
The offsetTop attribute must run these steps:
1. If the visual viewport's associated document is not fully active, return 0.
1. Otherwise, return the offset of the top edge of the visual viewport from the top edge
of the layout viewport.
The pageLeft attribute must run these steps:
1. If the visual viewport's associated document is not fully active, return 0.
1. Otherwise, return the offset of the left edge of the visual viewport from the left edge
of the initial containing block of the layout viewport's document.
The pageTop attribute must run these steps:
1. If the visual viewport's associated document is not fully active, return 0.
1. Otherwise, return the offset of the top edge of the visual viewport from the top edge
of the initial containing block of the layout viewport's document.
The width attribute must run these steps:
1. If the visual viewport's associated document is not fully active, return 0.
1. Otherwise, return the width of the visual viewport excluding the width of any rendered vertical classic
scrollbar that is fixed to the visual viewport.
Note: Since this value is returned in CSS pixels, the value will decrease in magnitude if either page zoom or the
scale factor is increased.
Note: A scrollbar that is fixed to the visual viewport is one that does not change size or location as the visual
viewport is zoomed and panned. Because this value is in CSS pixels, when excluding the scrollbar width the UA must
account for how large the scrollbar is as measured in CSS pixels. That is, the amount excluded decreases when zooming in
and increases when zooming out.
The height attribute must run these steps:
1. If the visual viewport's associated document is not fully active, return 0.
1. Otherwise, return the height of the visual viewport excluding the height of any rendered horizontal classic
scrollbar that is fixed to the visual viewport.
The scale attribute must run these steps:
1. If the visual viewport's associated document is not fully active, return 0
and abort these steps.
1. If there is no output device, return 1 and abort these steps.
1. Otherwise, return the visual viewport's scale factor.
onresize is the event handler IDL attribute for the resize event.
onscroll is the event handler IDL attribute for the scroll event.
onscrollend is the event handler IDL attribute for the scrollend event.
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.
1. If the {{VisualViewport}} associated with doc has had its scale,
width, or height properties changed since
the last time these steps were run, fire an event named resize at the {{VisualViewport}}.
| Event | Interface | Interesting targets | Description |
|---|---|---|---|
| resize | {{Event}} | {{Window}}, {{VisualViewport}} | Fired at the {{Window}} when the viewport is resized. Fired at {{VisualViewport}} when the visual viewport is resized or the layout viewport is scaled. |
| scroll | {{Event}} | {{VisualViewport}}, {{Document}}, elements | Fired at the {{VisualViewport}}, {{Document}} or element when the {{VisualViewport}}, viewport, or element is scrolled, respectively. |
| scrollend | {{Event}} | {{Document}}, elements, {{VisualViewport}} | Fired at the {{VisualViewport}}, {{Document}}, or element when a scroll is completed: the {{VisualViewport}}, viewport, or element has been scrolled, the scroll sequence has ended and any scroll offset changes have been applied. |
DOMRectList interface was removed.
* The {{Document/scrollingElement}} IDL attribute on {{Document}} was added.
* Some readonly attributes on {{Window}} were annotated with [Replaceable] IDL extended
attribute.
* {{MediaQueryList}}, scroll event and resize event are integrated with
the event loop in HTML so they are synchronized with animation frames.
* The instant value of 'scroll-behavior' was renamed to ''scroll-behavior/auto''.
* The origin of {{Element/scrollLeft}} on {{Element}} was changed (for RTL).
* The {{Element/scrollIntoView()}} method on {{Element}} and {{Window/scroll()}},
{{Window/scrollTo()}} and {{Window/scrollBy()}} methods on {{Window}} take the relevant
dictionary as the first argument.
* The {{MediaQueryList}} interface was changed to use regular event API and define
{{MediaQueryList/addListener()}} in terms of that.
features argument to window.open() is now defined.
* The {{Screen/colorDepth}} and {{Screen/pixelDepth}} attributes of {{Screen}} now always return 24.
* The {{Document/elementsFromPoint()}} method of {{Element}} is introduced.
* The specification is now aware of transforms.
* Some geometry utility APIs are introduced but are not yet specified.
* ClientRect has been renamed to {{DOMRect}} and has moved to the Geometry specification. [[GEOMETRY-1]]
* The specification now defines when the resize and scroll events fire.
Acknowledgements {#acks}
==================================================
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.