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, in speech, 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.

GitHub Issues are preferred for discussion of this specification.
When filing an issue, please put the text “cssom-view” in the title,
preferably like this:
“[cssom-view] …summary of comment…”.
All issues and comments are archived,
and there is also a historical archive.

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
couple of new features that will hopefully be useful to authors. (If they
are not you can bug us!)

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.

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.

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.

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.

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

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.

2.1. CSS pixels

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

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.

3. Common Infrastructure

3.1. Scrolling

When a user agent is to perform a scroll of a scrolling boxbox,
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:

When a user agent is to perform a smooth scroll of a scrolling boxbox 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 boxbox 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:

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

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.

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.

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 x CSS pixels of target and the distance between the top and bottom edges of the viewport are y CSS pixels of target.

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

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.

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:

Act as if the scroll() method was invoked with options as the only argument.

The screenX attribute 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 pixels, or zero if there is no such
thing.

The screenY attribute 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 pixels, or zero if there is no such
thing.

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

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

The devicePixelRatio attribute must return the result of the following algorithm:

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

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.

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

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

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 output device, measured in CSS pixels of target. The positive axis is rightward.

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

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 output device, measured in CSS pixels of target. The positive axis is downward.

Append an event listener to the associated list of event listeners with type set to change, callback set to listener,
and capture set to false,
unless there already is an event listener in that list
with the same type, callback, and capture.

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.

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.

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

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:

Let sequence be a new empty sequence.

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.

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.

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

Return sequence.

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

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.

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.

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:

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:

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.

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

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.

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

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

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

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

Return a sequence containing static 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:

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.

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

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

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

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.

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.

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.

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.

The getClientRects() method, when invoked, must return an empty
sequence if the range is not in the document and
otherwise a sequence object containing
static 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 getClientRects() on the element.

For each Text node selected or partially selected by the range (including when the
boundary-points are identical), include a 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.

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

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

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.

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.

12. Events

12.1. Resizing viewports

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

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.

The scroll-behavior property specifies the scrolling behavior for a scrolling box,
when scrolling happens due to navigation or CSSOM scrolling APIs.
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.

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.

Conformance classes

Conformance to this specification
is defined for three conformance classes:

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.

Requirements for Responsible Implementation of CSS

The following sections define several conformance requirements
for implementing CSS responsibly,
in a way that promotes interoperability in the present and future.

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 property 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

Implementations of CR-level Features

Once a specification reaches the Candidate Recommendation stage,
implementers should release an unprefixed implementation
of any CR-level feature they can demonstrate
to be correctly implemented according to spec,
and should avoid exposing a prefixed variant of that feature.

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.