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: WD
Date: 2025-09-16
Prepare for TR: yes
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
WPT Path Prefix: css/cssom-view/
WPT Display: open
Include Can I Use Panels: true
Can I Use URL: https://drafts.csswg.org/cssom-view-1/
Can I Use URL: https://www.w3.org/TR/cssom-view-1/
Ignore Can I Use URL Failure: https://drafts.csswg.org/cssom-view-1/

spec:css-ui-4; type:property; text:pointer-events
spec:css-viewport; type:dfn; text:effective zoom
spec:css2; type:dfn;
    text: canvas
    text: viewport
spec:dom; type:dfn; text:parent element
spec:html; type:dfn;
    text: inert
    text: the body element
    text: rules for parsing integers
    text: being rendered
spec:html; type:element; text:body
spec:css-overflow-3; type:property; text:scroll-behavior
spec:css-overflow-3; type:value; text:smooth
spec:css-overflow-3; type:value; text:auto
spec:css2; type:dfn; for:/; text:media
spec:css-scoping-1; type:dfn; text:shadow root
spec:dom; type:dfn; text:host
spec:dom; type:dfn; text:element
spec:dom; type:dfn; for:Attr; text:element
spec:css-borders-4; type:property; text:border-top-width
spec:css-borders-4; type:property; text:border-left-width
spec:cssom-view-1; type:dictionary; text:MouseEventInit
spec:cssom-view-1; type:dfn; for:MediaQueryList; text:media

Background

Terminology

If the overflow directions are rightward and downward

The top and left edges.

If the overflow directions are leftward and downward

The top and right edges.

If the overflow directions are leftward and upward

The bottom and right edges.

If the overflow directions are rightward and upward

The bottom and left edges.

If the overflow directions are rightward and downward

The bottom and right edges.

If the overflow directions are leftward and downward

The bottom and left edges.

If the overflow directions are leftward and upward

The top and left edges.

If the overflow directions are rightward and upward

The top and right edges.

CSS pixels

Zooming

Web-exposed screen information

Common Infrastructure

Scrolling

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

WebIDL values

Extensions to the {{Window}} Interface

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

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

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

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

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

    // viewport scrolling
    [Replaceable] readonly attribute double scrollX;
    [Replaceable] readonly attribute double pageXOffset;
    [Replaceable] readonly attribute double scrollY;
    [Replaceable] readonly attribute double pageYOffset;
    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;
};

1. Let parsed media query list be the result of parsing query.
2. Return a new {{MediaQueryList}} object, with [=this=]'s associated Document as the document, with parsed media query list as its associated [=MediaQueryList/media query list=].

var viewportWidth = innerWidth

If the viewport has rightward overflow direction

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

If the viewport has leftward overflow direction

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

If the viewport has downward overflow direction

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

If the viewport has upward overflow direction

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

The features argument to the {{Window/open()}} method

width

The width of the viewport.

height

The height of the viewport.

left

The left position of the window.

top

The top position of the window.

The {{MediaQueryList}} Interface

1. For each {{MediaQueryList}} object target that has doc as its document, in the order they were created, oldest first, run these substeps:
   1. If target's matches state has changed since the last time these steps were run, fire an event named change at target using {{MediaQueryListEvent}}, with its {{Event/isTrusted}} attribute initialized to true, its {{MediaQueryList/media}} attribute initialized to target's media, and its {{MediaQueryListEvent/matches}} attribute initialized to target's matches state.

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

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

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

Event summary

The {{Screen}} Interface

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

Extensions to the {{Document}} Interface

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

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

The 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. elementsFromPoint-iframes.html elementsFromPoint-inline-htb-ltr.html elementsFromPoint-inline-htb-rtl.html elementsFromPoint-inline-vlr-ltr.html elementsFromPoint-inline-vlr-rtl.html elementsFromPoint-inline-vrl-ltr.html elementsFromPoint-inline-vrl-rtl.html elementsFromPoint-invalid-cases.html elementsFromPoint-shadowroot.html elementsFromPoint-simple.html elementsFromPoint-svg-text.html elementsFromPoint-svg.html elementsFromPoint-table.html elementsFromPoint.html The caretPositionFromPoint(x, y, options) method must return the result of running these steps: 1. If there is no viewport associated with the document, return null. 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:

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.

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. scroll-overflow-clip-quirks-001.html scroll-overflow-clip-quirks-002.html scrollingElement-quirks-dynamic-001.html scrollingElement-quirks-dynamic-002.html scrollingElement.html

The {{CaretPosition}} Interface

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

Extensions to the {{Element}} Interface

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

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

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

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

  boolean checkVisibility(optional CheckVisibilityOptions options = {});

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

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

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

{{Element}} Scrolling Members

Extensions to the {{HTMLElement}} Interface

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

Extensions to the {{HTMLImageElement}} Interface

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

Extensions to the {{Range}} Interface

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

Extensions to the {{MouseEvent}} Interface

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

Geometry

The {{GeometryUtils}} Interface

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

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

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

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

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

1. DOM order p1 = top left even in RTL scale to 0 means divide by zero, return 0x0 cross-frames not allowed, throw WrongDocumentError? points are flattened (3d transform), z=0. like getClientRect test block in inline pseudo-elements before/after are children of the element viewport boxes are all the same

1. ...

1. ...

1. ...

VisualViewport

The {{VisualViewport}} Interface

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

Events

Resizing viewports

Scrolling

Event summary

Changes since the 17 March 2016 Working Draft

Changes since the 17 December 2013 Working Draft

Changes since the 04 August 2011 Working Draft

Changes since the 04 August 2009 Working Draft

Changes since the 22 February 2008 Working Draft