VisualViewport

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since August 2021.

* Some parts of this feature may have varying levels of support.

The VisualViewport interface of the Visual Viewport API represents the visual viewport for a given window. For a page containing iframes, each iframe, as well as the containing page, will have a unique window object. Each window on a page will have a unique VisualViewport representing the properties associated with that window.

You can get a window's visual viewport using Window.visualViewport.

Note: Only the top-level window has a visual viewport that's distinct from the layout viewport. Therefore, it's generally only the VisualViewport object of the top-level window that's useful. For an <iframe>, visual viewport metrics like VisualViewport.width always correspond to layout viewport metrics like document.documentElement.clientWidth.

EventTarget VisualViewport

Instance properties

Also inherits properties from its parent interface, EventTarget.

VisualViewport.offsetLeft Read only

Returns the offset of the left edge of the visual viewport from the left edge of the layout viewport in CSS pixels.

VisualViewport.offsetTop Read only

Returns the offset of the top edge of the visual viewport from the top edge of the layout viewport in CSS pixels.

VisualViewport.pageLeft Read only

Returns the x coordinate of the visual viewport relative to the initial containing block origin of the top edge in CSS pixels.

VisualViewport.pageTop Read only

Returns the y coordinate of the visual viewport relative to the initial containing block origin of the top edge in CSS pixels.

VisualViewport.width Read only

Returns the width of the visual viewport in CSS pixels.

VisualViewport.height Read only

Returns the height of the visual viewport in CSS pixels.

VisualViewport.scale Read only

Returns the pinch-zoom scaling factor applied to the visual viewport.

Instance methods

Also inherits methods from its parent interface, EventTarget.

Events

Listen to these events using addEventListener() or by assigning an event listener to the relevant oneventname property of this interface.

resize

Fired when the visual viewport is resized. Also available via the onresize property.

scroll

Fired when the visual viewport is scrolled. Also available via the onscroll property.

scrollend

Fired when a scrolling operation on the visual viewport ends. Also available via the onscrollend property.

Examples

Hiding an overlaid box on zoom

This example, taken from the Visual Viewport README, shows how to write a bit of code that will hide an overlaid box (which might contain an advert, say) when the user zooms in. This is a nice way to improve the user experience when zooming in on pages. A live sample is also available.

js
const bottomBar = document.getElementById("bottom-bar");
const viewport = window.visualViewport;

function resizeHandler() {
  bottomBar.style.display = viewport.scale > 1.3 ? "none" : "block";
}

window.visualViewport.addEventListener("resize", resizeHandler);

Simulating position: device-fixed

This example, also taken from the Visual Viewport README, shows how to use this API to simulate position: device-fixed, which fixes elements to the visual viewport. A live sample is also available.

js
const bottomBar = document.getElementById("bottom-bar");
const viewport = window.visualViewport;
function viewportHandler() {
  const layoutViewport = document.getElementById("layoutViewport");

  // Since the bar is position: fixed we need to offset it by the visual
  // viewport's offset from the layout viewport origin.
  const offsetLeft = viewport.offsetLeft;
  const offsetTop =
    viewport.height -
    layoutViewport.getBoundingClientRect().height +
    viewport.offsetTop;

  // You could also do this by setting style.left and style.top if you
  // use width: 100% instead.
  bottomBar.style.transform = `translate(${offsetLeft}px, ${offsetTop}px) scale(${
    1 / viewport.scale
  })`;
}
window.visualViewport.addEventListener("scroll", viewportHandler);
window.visualViewport.addEventListener("resize", viewportHandler);

Note: This technique should be used with care; emulating position: device-fixed in this way can result in the fixed element flickering during scrolling.

Specifications

Specification
CSSOM View Module
# the-visualviewport-interface

Browser compatibility

Report problems with this compatibility data on GitHub
desktopmobile
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
VisualViewport
height
offsetLeft
offsetTop
pageLeft
pageTop
resize event
scale
scroll event
scrollend event
width

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
No support
No support
See implementation notes.
Has more compatibility info.

See also

  • Web Viewports Explainer — useful explanation of web viewports concepts, including the difference between visual viewport and layout viewport.