Definition of the visual viewport

The visual viewport is a kind of viewport whose scrolling area is another viewport, called the layout viewport.

In addition to scrolling, the visual viewport also allows applying a scale transform to its layout viewport. This transform is applied to the canvas of the layout viewport and does not affect its internal coordinate space.

The magnitude of the scale transform is known as the visual viewport's scale factor

The window object has an associated visual viewport which is a VisualViewport object. Every visual viewport is associated with exactly one window object that never changes. The associated document of a visual viewport is the associated document of its associated window.

Extensions to the Window interface

This document extends the Window interface defined by [[HTML]].

            partial interface Window {
              [SameObject, Replaceable] readonly attribute VisualViewport? visualViewport;
            };
          

visualViewport

If the associated document is fully active, return the VisualViewport object associated with the window. Otherwise, return null.

Intuitively, the VisualViewport object is only returned and useful for a window whose Document is currently being presented. If a reference is retained to a VisualViewport whose associated Document is not being currently presented, the values in that VisualViewport must not reveal any information about the browsing context.

The VisualViewport interface

A VisualViewport object represents the visual viewport a document is being presented in if it is fully active. Each window in a page has its own distinct VisualViewport object.

A document being presented in any browsing context, including a nested browsing context, will have its own visual viewport. However, most user agents modify the visual viewport only on a top-level browsing context. The visual viewport in a nested browsing context is provided for ergonomic reasons.

For example: if a script retains a reference to a VisualViewport for an iframe, then navigates the iframe to another location, reading the integral values from the VisualViewport reference will return 0 because its window's Document is no longer being presented in a browsing content; it is no longer fully-active.

Unless otherwise stated, all returned values in this section are defined in CSS pixels.

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

              readonly attribute FrozenArray<DOMRect>? segments;

              attribute EventHandler onresize;
              attribute EventHandler onscroll;
            };
          

offsetLeft

If the visual viewport's associated document is not fully active, return 0.

Otherwise, return the offset of the left edge of the visual viewport from the left edge of the layout viewport.

offsetTop

If the visual viewport's associated document is not fully active, return 0.

Otherwise, return the offset of the top edge of the visual viewport from the top edge of the layout viewport.

pageLeft

If the visual viewport's associated document is not fully active, return 0.

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.

pageTop

If the visual viewport's associated document is not fully active, return 0.

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.

width

If the visual viewport's associated document is not fully active, return 0.

Otherwise, return the width of the visual viewport in CSS pixels. This value excludes the width of any rendered classic scrollbar that is fixed to the visual viewport.

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 in CSS pixels. That is, the amount excluded is lessened if the viewport is zoomed in and the scrollbars don't change size to the user.

height

If the visual viewport's associated document is not fully active, return 0.

Otherwise, return the height of the visual viewport in CSS pixels. This value excludes the height of any rendered classic scrollbar that is fixed to the visual viewport.

Because both the width and height attributes are expressed in CSS pixels, increasing either page-zoom or pinch-zoom will cause these values to shrink.

scale

Returns the visual viewport's scale factor. It can be computed using the following algorithm:

Although often referred to as the pinch-zoom scale factor, it can be affected through means other than pinch-zooming. e.g. When the user agent centers and zooms in on a focused input element.

1. If the visual viewport's associated document is not fully active, return 0 and abort these steps.

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

3. Let CSS pixel size be the size of a CSS reference pixel scaled by the current page zoom and the scale factor of the visual viewport associated with this window

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

5. Let device independent pixel size be the product of device pixel size and the devicePixelRatio

   Visual viewport scale (e.g. pinch-zoom) does not affect the devicePixelRatio.

6. Return the result of dividing the CSS pixel size by the device independent pixel size.

segments

The viewport segments property is currently in development and considered experimental.

Returns an array of DOMRects that represent the dimensions of each existing viewport segment.

A viewport segment represents the region of the visual viewport that resides on a separate display or logical display region. When the visual viewport spans across some number of physical features of a device, these features in turn convey a logical separation of the space available for content.

segments is null when there is only a single viewport segment. Returns null when called from within an iframe context.

Based on the data returned for each viewport segment, developers will be able to infer the number of hinges available as well as the hinge orientation. The browser window can be moved/resized such that the number of segments and/or their dimensions change. In these cases, resize events will fire at which point authors should re-query this property, as the returned FrozenArray is just a snapshot of the current state.

onresize

Event handler attribute for the resize event.

onscroll

Event handler attribute for the scroll event.

Additions to the CSSOM-VIEW Events section

Append following step as the last step of run the resize steps:

Replace step 1.1 of run the scroll steps with: