CSSOM View Module

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.

Status of this Document

Table of Contents

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 identical way without differences between quirks, limited quirks and no quirks mode, as defined by HTML5. [HTML5]

As well as serving as a specification for that "de facto" standard this specification also obsoletes DOM Level 2 Views by removing the views concept and the interfaces defined by that specification and relocating the members of those interfaces to more appropriate places.

Finally, the specification defines a couple of new features that will hopefully be useful to Web authors. (If they are not you can bug us!)

Conformance Criteria

Everything in this specification is normative except for diagrams, examples, notes and sections marked non-normative.

The key word must in this document is to be interpreted as described in RFC 2119. [RFC2119]

A conforming user agent implements all the requirements made by this specification.

Web IDL

The IDL fragments in this specification must be interpreted as required for conforming IDL fragments, as described in the Web IDL specification. [WebIDL]

Terminology

Document and Element are defined by DOM Level 3 Core. [DOM3Core]

Range is defined in DOM Level 2 Traversal and Range. [DOM2TR]

MouseEvent is defined in DOM Level 2 Events. [DOM2Events]

Compare lists of media queries and parse a list of media queries are defined by the CSSOM. [CSSOM]

HTML element, HTMLElement, queue a task, task, and Window are defined by HTML5. [HTML5]

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

Content edge, padding edge, border edge, and canvas are defined by CSS 2.1. [CSS21]

Viewport and initial containing block are defined by CSS 2.1 unless there is an ancestor foreignObject element in the http://www.w3.org/2000/svg namespace in which case that element acts as viewport and initial containing block. [CSS21] [SVG]

The term content refers to the dimensions of the element's content area, including overflown content. [CSS21]

The term document content refers to the area on the canvas that is rendered upon, excluding content on negative axis.

CSS pixels

All coordinates and dimensions for the APIs defined in this specification are in CSS pixels. [CSS21]

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

DOM Features

This specification defines the DOM feature "Views" for versions "2.0" and "3.0". User agents supporting this specification must support that feature and versions. [DOM3Core]

Authors are encouraged to stay away from DOM features as user agents claiming to support the DOM feature might not support the feature you need and user agents supporting parts of the specification might not claim support for the DOM feature.

Extensions to the Window Interface

[Supplemental] interface Window {
  readonly attribute StyleMedia styleMedia;
  readonly attribute Screen screen;

  // viewport
  readonly attribute long innerWidth;
  readonly attribute long innerHeight;
  readonly attribute long pageXOffset;
  readonly attribute long pageYOffset;
  void scroll(long x, long y);
  void scrollTo(long x, long y);
  void scrollBy(long x, long y);

  // client
  readonly attribute long screenX;
  readonly attribute long screenY;
  readonly attribute long outerWidth;
  readonly attribute long outerHeight;
};

The styleMedia attribute must return the StyleMedia object associated with the Window object. It always returns the same object.

The screen attribute must return the Screen object associated with the Window object. It always returns the same object.

The innerWidth attribute must return the viewport width including the size of a rendered scroll bar (if any).

var viewportWidth = innerWidth

The innerHeight attribute must return the viewport height including the size of a rendered scroll bar (if any).

The pageXOffset attribute must return the x-coordinate, relative to the initial containing block origin, of the left of the viewport.

The pageYOffset attribute must return the y-coordinate, relative to the initial containing block origin, of the top of the viewport.

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

1. If either x or y is infinite or NaN stop this algorithm.

2. If document content can have overflow to the right

   1. Let x be min(x, content width - content edge width).

   2. If x is negative let it be zero.

   If document content can have overflow to the left (under right-to-left conditions)

   1. Let x be max(x, content edge width - content width).

   2. If x is non-negative let it be zero.

3. Let y be min(y, document content height - viewport height excluding the size of a rendered scroll bar (if any)).

4. If y is negative let it be zero.

5. Align the x-coordinate x of the document content with the left of the viewport and align the y-coordinate y of the document content with the top of the viewport.

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

When the scrollBy(x,y) method is invoked, the user agent must act as if the scroll() method was invoked with x plus pageXOffset as first argument and y plus pageYOffset as second argument.

The screenX attribute must return the x-coordinate, relative to the origin of the screen of the output device, of the top 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 output device, of the left 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 StyleMedia Interface

interface StyleMedia {
  readonly attribute DOMString type;
  boolean matchMedia(DOMString mq_list);

  void addMediaListener(DOMString mq_list, BooleanCallback mq_callback);
  void removeMediaListener(DOMString mq_list, BooleanCallback mq_callback);
};

[Callback=FunctionOnly, NoInterfaceObject]
interface BooleanCallback {
  void handleEvent(boolean arg);
};

The type attribute must return the string that represents the media type used for rendering the Document. The media types are defined by CSS 2.1 (screen, print, et cetera). [CSS21]

var isProjection = media.type == "projection"

The matchMedia(mq_list) method must run these steps:

1. Let parsed_mq_list be the result of parsing mq_list.

2. If parsed_mq_list is null terminate these steps.

3. If parsed_mq_list matches the state of the rendered Document return true and terminate this algorithm.

4. Otherwise, return false.

var isColorDevice = styleMedia.matchMedia("(color)")

Each Window has an associated ordered list of media listeners. Each listener consists of a list of media queries and a callback.

Due to the rules for addMediaListener() below each listener is unique. Lists of media queries and callbacks are not necessarily unique.

The addMediaListener(mq_list, mq_callback) method must run these steps:

1. Let parsed_mq_list be the result of parsing mq_list.

2. If parsed_mq_list is null terminate these steps.

3. If comparing parsed_mq_list with any of the list of media queries in the list of media listeners returns true and the associated callback of that media query is the same as mq_callback, terminate these steps.

4. Append the tuple of parsed_mq_list and mq_callback to the list of media listeners.

The removeMediaListener(mq_list, mq_callback) method must run these steps:

1. Let parsed_mq_list be the result of parsing mq_list.

2. If parsed_mq_list is null terminate these steps.

3. If comparing parsed_mq_list with any of the media queries in the list of media listeners returns true and the associated callback of that media query is the same as mq_callback, remove the tuple of parsed_mq_list and mq_callback from the list of media listeners.

If one or more lists of media queries in the list of media listeners changes in evaluation then for each list of media queries of which the evaluation changes, in the order of the list of media listeners, queue a task that invokes the associated callback, passing as argument whether the list of media queries matches the state of the rendered Document at the time the task was queued.

function handleOrientationChange(landscape) {
  if(landscape)
    …
  else
    …
}
styleMedia.addMediaListener("(orientation:landscape)", handleOrientationChange)

function handleMediaQueryChange(query, matches) {
  …
}
function addMediaListener(query) {
  styleMedia.addMediaListener(
    query,
    function(matches) { handleMediaQueryChange(query, matches) }
  )
}

The Screen Interface

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

interface Screen {
  readonly attribute unsigned long availWidth;
  readonly attribute unsigned long availHeight;
  readonly attribute unsigned long width;
  readonly attribute unsigned long height;
  readonly attribute unsigned long colorDepth;
  readonly attribute unsigned long pixelDepth;
};

The availWidth attribute must return the available width of the rendering surface of the output device.

The availHeight attribute must return the available height of the rendering surface of the output device.

The width attribute must return the width of the output device.

The height attribute must return the height of the output device.

The colorDepth and pixelDepth attributes must both return the number of bits allocated to colors in the output device. If the output device does not support colors these attributes must return zero.

Bits allocated to handling transparency are not taken into account.

Extensions to the Document Interface

[Supplemental] interface Document {
  Element elementFromPoint(float x, float y);
  CaretPosition caretPositionFromPoint(float x, float y);
};

The elementFromPoint(x, y) method, when invoked, must return the element at coordinates x,y in the viewport. The element to be returned is determined through hit testing. 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 greather than the viewport height excluding the size of a rendered scroll bar (if any), the method must return null. If there is no element at the given position the method must return the root element, if any, or null otherwise.

The caretPositionFromPoint(x, y) method, when invoked, must return the result of running 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), y is greather than the viewport height excluding the size of a rendered scroll bar (if any) return null.

2. If at the coordinates x,y in the viewport no text insertion point indicator would have been inserted return null.

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

4. 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 and the other properties are set as follows:

   caret node

   The startContainer of the caret range.

   caret offset

   The startOffset of the caret range.

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

The CaretPosition Interface

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.

interface CaretPosition {
  readonly attribute Node offsetNode;
  readonly attribute unsigned long offset;
  readonly attribute Range range;
};

The offsetNode attribute must return the caret node.

The offset attribute must return the caret offset.

The range attribute must return the caret range.

Extensions to the Element Interface

[Supplemental] interface Element {
  ClientRectList getClientRects();
  ClientRect getBoundingClientRect();

           attribute long scrollTop;   // scroll on setting
           attribute long scrollLeft;  // scroll on setting
  readonly attribute long scrollWidth;
  readonly attribute long scrollHeight;

  readonly attribute long clientTop;
  readonly attribute long clientLeft;
  readonly attribute long clientWidth;
  readonly attribute long clientHeight;
};

The getClientRects() and getBoundingClientRect() methods

The getClientRects() and getBoundingClientRect methods provide information about the position of the border box edges of an element relative to the viewport. The objects these methods return must be static. That is, changes to the underlying document are not reflected in the objects.

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 layout box and is not in the http://www.w3.org/2000/svg namespace return an empty ClientRectList object and stop this algorithm.

2. If the element does not have an associated CSS layout box and is in the http://www.w3.org/2000/svg namespace return a ClientRectList object containing a single ClientRect object that describes the bounding box of the element as defined by SVG specification. [SVG]

3. Return a ClientRectList object containing a list of ClientRect objects in content order describing the border boxes (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 display property of table or inline-table include both the table box and the caption box, if any, but not the anonymous container box. [CSS21]

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

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 ClientRect object whose top, right, bottom and left members are zero.

3. Otherwise, return a ClientRect object describing the smallest rectangle that includes the first rectangle in list and all of the remaining rectangles of which the height or width is not zero.

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

The scrollTop, scrollLeft, scrollWidth, and scrollHeight attributes

The scrollTop attribute, when called on element A, must return the value that is the result of running the following algorithm:

1. If A does not have an associated CSS layout box return zero and stop this algorithm.

2. Return the y-coordinate of the content at the alignment point with the top of the content edge of A.

When setting the scrollTop attribute to y on element A user agents must run the following algorithm:

1. If A does not have an associated CSS layout box or vertical overflow stop this algorithm.

2. If y is infinite or NaN stop this algorithm.

3. Let y be min(y, content height - content edge height).

4. If y is negative let it be zero.

5. Align content y-coordinate y with the top of the content edge of A.

The scrollLeft attribute, when called on element A, must return the value that is the result of running the following algorithm:

1. If A does not have an associated CSS layout box return zero and stop this algorithm.

2. Return the x-coordinate of the content at the alignment point with the left of the content edge of A.

When setting the scrollLeft attribute to x on element A user agents must run the following algorithm:

1. If A does not have an associated CSS layout box or horizontal overflow stop this algorithm.

2. If x is infinite or NaN stop this algorithm.

3. If A can have overflow to the right

   1. Let x be min(x, content width - content edge width).

   2. If x is negative let it be zero.

   If A can have overflow to the left (under right-to-left conditions)

   1. Let x be max(x, content edge width - content width).

   2. If x is non-negative let it be zero.

4. Align content x-coordinate x with the left of the content edge of A.

The scrollWidth attribute, when called on element A, must return value that is the result of the following algorithm:

1. If A does not have an associated CSS layout box return zero and stop this algorithm.

2. Return the computed value of the padding-left property of A, plus the computed value of the padding-right property of A, plus the content width of A.

The scrollHeight attribute, when called on element A, must return value that is the result of the following algorithm:

1. If A does not have an associated CSS layout box return zero and stop this algorithm.

2. Return the computed value of the padding-top property of A, plus the computed value of the padding-bottom property of A, plus the content height of A.

The clientTop, clientLeft, clientWidth, and clientHeight attributes

The clientTop, clientLeft, clientWidth, and clientHeight attributes must return zero if the element does not have an associated CSS layout box or if the layout box is inline. Otherwise, these attributes must behave as defined in the remainder of this section.

The clientTop attribute returns the computed value of the border-top-width property plus the width of any scrollbar rendered between the top padding edge and the top border edge.

The clientLeft attribute returns 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.

The clientWidth attribute returns the viewport width excluding the size of a rendered scroll bar (if any) if the element is the root element and the width of the padding edge (excluding the width of any rendered scrollbar between the padding edge and the border edge) otherwise.

The clientHeight attribute returns the viewport height excluding the size of a rendered scroll bar (if any) if the element is the root element and the height of the padding edge (excluding the width of any rendered scrollbar between the padding edge and the border edge) otherwise.

Extensions to the HTMLElement Interface

[Supplemental] interface HTMLElement {
  readonly attribute Element offsetParent;
  readonly attribute long offsetTop;
  readonly attribute long offsetLeft;
  readonly attribute long offsetWidth;
  readonly attribute long offsetHeight;
};

The offsetParent, offsetTop, offsetLeft, offsetWidth, and offsetHeight attributes

The offsetParent attribute, when called on element A, must return the element determined by the following algorithm:

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

   • A does not have an associated CSS layout box.
   • A is the root element.
   • A is the HTML body element.
   • The computed value of the position property for element A is fixed.

2. If A is an area HTML element which has a map HTML element somewhere in the ancestor chain return the nearest ancestor map HTML element and stop this algorithm.

3. Return the nearest ancestor element of A for which at least one of the following is true and stop this algorithm if such an ancestor is found:

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

4. Return null.

The offsetTop attribute, when called on element A, must return the value that is the result of the following algorithm:

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

2. If the offsetParent of A is null or the HTML body element return the y-coordinate of the top border edge of A and stop this algorithm.

3. Return the result of subtracting the y-coordinate of the top padding edge of the offsetParent of A from the y-coordinate of the top border edge of A, relative to the initial containing block origin.

   In case of an inline element that consists of multiple line boxes only the first in content order is to be considered for the purposes of the above algorithm.

The offsetLeft attribute, when called on element A, must return the value that is the result of the following algorithm:

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

2. If the offsetParent of A is null or the HTML body element return the x-coordinate of the left border edge of A and stop this algorithm.

3. Return the result of subtracting the x-coordinate of the left padding edge of the offsetParent of A from the x-coordinate of the left border edge of A, relative to the initial containing block origin.

   In case of an inline element that consists of multiple line boxes only the first in content order is to be considered for the purposes of the above algorithm.

The offsetWidth attribute, when called on element A, must return value that is the result of the following algorithm:

1. If A does not have an associated CSS layout box return zero and stop this algorithm.

2. Return the border edge width of A.

The offsetHeight attribute, when called on element A, must return value that is the result of the following algorithm:

1. If A does not have an associated CSS layout box return zero and stop this algorithm.

2. Return the border edge height of A.

Extensions to the Range Interface

[Supplemental] interface Range {
  ClientRectList getClientRects();
  ClientRect getBoundingClientRect();
};

The objects the methods described below return must be static.

The getClientRects() method, when invoked, must return an empty ClientRectList object if the range is not in the document and otherwise a ClientRectList object containing a list of ClientRect 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 boxes 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 ClientRect object (for the part that is selected, not the whole line box). The bounds of these ClientRect 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.

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 ClientRect object whose top, right, bottom and left members are zero.

3. Otherwise, return a ClientRect object describing the smallest rectangle that includes the first rectangle in list and all of the remaining rectangles of which the height or width is not zero.

Extensions to the MouseEvent Interface

[Supplemental] interface MouseEvent {
  readonly attribute long screenX;
  readonly attribute long screenY;

  readonly attribute long pageX;
  readonly attribute long pageY;

  readonly attribute long clientX;
  readonly attribute long clientY;
  readonly attribute long x;
  readonly attribute long y;

  readonly attribute long offsetX;
  readonly attribute long offsetY;
};

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

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

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

The pageX attribute must return the horizontal coordinate of the position where the event occurred relative to the origin of the initial containing block.

The pageY attribute must return the y-coordinate of the position where the event occurred relative to the origin of the initial containing block.

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

The y attribute must return the value of clientY.

The offsetX attribute must return the x-coordinate of the position where the event occurred relative to the origin of the padding edge of the target node.

The offsetY attribute must return the y-coordinate of the position where the event occurred relative to the origin of the padding edge of the target node.

Rectangles

The ClientRectList Interface

The ClientRectList object consists of an ordered list of ClientRect objects.

interface ClientRectList {
  readonly attribute unsigned long length;
  getter ClientRect item(unsigned long index);
};

The length attribute must return the total number of ClientRect objects associated with the object.

The item(index) method, when invoked, must raise an INDEX_SIZE_ERR exception when index is negative or greater than the number of ClientRect objects associated with the object. Otherwise, the ClientRect object at index must be returned.

The ClientRect Interface

Objects implementing the ClientRect interface represent a rectangular box. The type of box is specified by the method that returns a ClientRect object.

interface ClientRect {
  readonly attribute float top;
  readonly attribute float right;
  readonly attribute float bottom;
  readonly attribute float left;
  readonly attribute float width;
  readonly attribute float height;
};

The top attribute must return the y-coordinate, relative to the viewport origin, of the top of the rectangle box.

The right attribute must return the x-coordinate, relative to the viewport origin, of the right of the rectangle box.

The bottom attribute must return the y-coordinate, relative to the viewport origin, of the bottom of the rectangle box.

The left attribute must return the x-coordinate, relative to the viewport origin, of the left of the rectangle box.

The width attribute must return the width of the rectangle box.

This is identical to right minus left.

The height attribute must return the height of the rectangle box.

This is identical to bottom minus top.

References

All references are normative.

[CSS21]

Cascading Style Sheets Level 2 Revision 1, B. Bos, T. Çelik, I. Hickson, H. Wium Lie. W3C.

[CSSOM]

CSSOM (work in progress), A. van Kesteren. W3C.

[DOM2Events]

Document Object Model (DOM) Level 2 Events Specification, T. Pixley. W3C.

[DOM2TR]

Document Object Model (DOM) Level 2 Traversal and Range Specification, J. Kesselman, J. Robie, M. Champion, P. Sharpe, V. Apparao, L. Wood. W3C.

[DOM3Core]

Document Object Model (DOM) Level 3 Core Specification, A. Le Hors, P. Le Hégaret, L. Wood, G. Nicol, J. Robie, M. Champion, S. Byrne. W3C.

[HTML5]

HTML5 (work in progress), I. Hickson. W3C.

HTML5 (work in progress), I. Hickson. WHATWG.

[RFC2119]

Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF.

[SVG]

Scalable Vector Graphics (SVG) 1.1 Specification, J. Ferraiolo, 藤沢 淳, D. Jackson. W3C.

[WebIDL]

Web IDL (work in progress), C. McCormack. W3C.

Acknowledgments

The editor would like to thank Alexey Feldgendler, Björn Höhrmann, David Vest, Garrett Smith, Hallvord R. M. Steen, Luiz Agostini, Maciej Stachowiak, Michael Dyck, Mike Wilson, Morten Stenshorne, Peter-Paul Koch, Rachel Kmetz, Robert O'Callahan, Sam Weinig, Simon Pieters, Sylvain Galineau, Tarquin Wilton-Jones, Thomas Moore, 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.