Visual Viewport API

Build viewport-aware web applications that adapt to pinch-zoom, on-screen keyboards, and modern mobile interactions

Understanding Viewports in Mobile Browsers

Modern mobile browsers operate with two distinct viewports. The layout viewport represents the total area of the web page as it's laid out by the browser, covering all elements regardless of what's visible. The visual viewport is what users actually see on their screens--a smaller, dynamic region that changes during scrolling and zooming.

This distinction is fundamental to understanding why traditional approaches fail on mobile devices. When users invoke the on-screen keyboard, browsers resize the visual viewport while often keeping the layout viewport dimensions unchanged. Similarly, pinch-zooming affects the visual viewport's scale and dimensions without altering layout viewport measurements. Without proper tracking, input fields can become hidden behind keyboards, action buttons get pushed off-screen, and users experience frustrating layout glitches.

Why This Matters for Your Applications

Before the Visual Viewport API, developers relied on properties like window.innerHeight and document.documentElement.clientHeight to approximate viewport information. These approaches work adequately for simple desktop layouts but fail dramatically in mobile contexts. The Window.scrollX and Window.scrollY properties report scroll position relative to the layout viewport, not the visual viewport--making them unreliable for tracking what users actually see during pinch-zoom operations.

The Visual Viewport API has been widely available across all major browsers since August 2021, meeting the Baseline criteria for modern web development. This API is part of the CSSOM View Module and provides native access to exactly what users see on their screens, enabling developers to build responsive, user-friendly interfaces that adapt to modern device behaviors.

By understanding and implementing this API, you create applications that feel polished and professional across the diverse ways users interact with content on modern devices--from pinch-zooming on articles to typing in form fields with on-screen keyboards.

For teams working on local web development workflows, understanding viewport behavior is essential for testing mobile-specific interactions in a development environment that mirrors production.

Key Visual Viewport Properties

Understanding each property enables precise viewport tracking and responsive layouts

width & height

Returns the actual visible dimensions in CSS pixels, updating during pinch-zoom operations unlike window.innerWidth/Height

scale

Returns the pinch-zoom scaling factor (1.0 = no zoom, 2.0 = 2x zoom) for calculating actual pixel sizes

offsetLeft & offsetTop

Returns the visual viewport position within the layout viewport, essential for repositioning fixed elements

pageLeft & pageTop

Returns coordinates relative to the initial containing block, useful for complex layout calculations

Accessing the Visual Viewport

The Visual Viewport API centers on the Window.visualViewport property, which returns a VisualViewport object representing the current window's visual viewport. This read-only property provides access to all viewport metrics and enables event listener attachment for tracking changes.

The following code demonstrates the basic API access pattern. Always check for API availability first, as older browsers may not support this feature. Once accessed, you can read properties like width, height, scale, offsetLeft, and offsetTop to understand the current viewport state.

Important Note: For pages containing iframes, only the top-level window's VisualViewport differs from the layout viewport. Within iframes, visual viewport metrics always correspond to layout viewport metrics.

When building APIs that need to communicate viewport state to backend services, understanding the fundamentals of REST API design helps architect clean, predictable endpoints for sharing this information across your application stack.

Accessing the Visual Viewport API

1const viewport = window.visualViewport;2 3// Check API availability4if (window.visualViewport) {5 console.log('Visual Viewport API is supported');6 console.log('Width:', viewport.width);7 console.log('Height:', viewport.height);8 console.log('Scale:', viewport.scale);9 console.log('Offset:', viewport.offsetLeft, viewport.offsetTop);10 console.log('Page position:', viewport.pageLeft, viewport.pageTop);11} else {12 console.warn('Visual Viewport API not supported');13}

Working with Visual Viewport Events

The Visual Viewport API provides three events for tracking viewport changes: resize, scroll, and scrollend. Each serves a distinct purpose in creating responsive, viewport-aware applications.

The resize Event

The resize event fires whenever the visual viewport is resized. This occurs during pinch-zoom operations, when the on-screen keyboard appears or disappears, when device orientation changes, or when browser chrome like the address bar expands or collapses. Unlike the standard window resize event, the visual viewport resize event captures these mobile-specific changes. Use this event to adjust layouts, reposition floating elements, or update UI states when the visible area changes.

The scroll Event

The scroll event fires when the visual viewport is scrolled, whether through user touch gestures, scroll wheel on desktop, or programmatic scrolling. On mobile browsers, offsetLeft and offsetTop typically update during pinch-zoom as the visual viewport moves through the layout viewport, rather than window.scrollX/scrollY. This event is essential for updating sticky elements, floating controls, or navigation states that should reflect the current visible position.

The scrollend Event

The scrollend event provides notification when a scrolling operation on the visual viewport completes. This is valuable for triggering actions that should only occur after scrolling settles, such as lazy-loading images, updating navigation states, or fetching additional content. By deferring expensive operations until scrolling completes, applications maintain smooth performance during rapid scrolling.

The following example demonstrates practical handling of all three events with use cases for each.

Handling Visual Viewport Events

1const viewport = window.visualViewport;2 3// Handle resize events - fires during pinch-zoom, keyboard, orientation changes4viewport.addEventListener('resize', () => {5 console.log('Viewport resized:', viewport.width, 'x', viewport.height);6 updateLayoutForViewport();7 adjustFixedElements();8});9 10// Handle scroll events - fires when visual viewport moves through layout11viewport.addEventListener('scroll', () => {12 console.log('Viewport scrolled to:', viewport.offsetLeft, viewport.offsetTop);13 repositionFloatingUI();14 updateStickyNavigation();15});16 17// Handle scroll completion - fires when scrolling settles18viewport.addEventListener('scrollend', () => {19 console.log('Scrolling completed at:', viewport.offsetLeft, viewport.offsetTop);20 finalizeScrollActions();21 lazyLoadVisibleImages();22});23 24// Example layout update function25function updateLayoutForViewport() {26 const vv = window.visualViewport;27 document.documentElement.style.setProperty('--vv-height', `${vv.height}px`);28 document.documentElement.style.setProperty('--vv-scale', String(vv.scale));29}

Practical Applications

Keeping Elements Visible During Zoom

A common challenge in mobile web development is maintaining visibility of important UI elements when users zoom into content. Fixed-position elements often move off-screen during pinch-zoom, creating frustrating user experiences. The Visual Viewport API enables precise positioning relative to the actual visible area by using offsetLeft and offsetTop to calculate positions within the current visual viewport.

The following code demonstrates a floating action button that stays positioned in the bottom-right corner regardless of zoom level or scroll position. By updating the button position on every resize and scroll event, the element remains accessible even when users zoom in to focus on specific content.

Handling On-Screen Keyboards

Mobile browsers display on-screen keyboards that reduce the available viewport height. Without proper handling, input fields and form controls can be obscured by the keyboard, blocking user interaction. The Visual Viewport API detects these changes by monitoring viewport height reductions, enabling appropriate layout adjustments.

This pattern detects significant viewport height changes (typically over 100px) that indicate keyboard activity, then adjusts form layouts by adding padding and ensuring the submit button scrolls into view. This approach ensures forms remain usable across different devices, keyboard sizes, and browser implementations.

Creating Zoom-Aware Layouts

Some interfaces require different behavior at different zoom levels. For example, a map interface might show minimal controls at overview zoom levels and detailed controls at high zoom levels. The Visual Viewport API's scale property enables these adaptations without relying on unreliable CSS media queries for zoom state.

By monitoring the scale property and updating UI classes accordingly, applications can provide context-appropriate controls. This pattern is particularly valuable for interactive content like maps, image galleries, and data visualizations where control density should match the current magnification level.

Supporting Foldable Devices

Modern foldable devices present multiple viewport regions that the Visual Viewport API, combined with the Viewport Segments API, can track. When a device unfolds, the viewport segments provide information about each visible region, enabling split-view layouts that take advantage of the additional screen real estate.

This pattern checks for viewport segment support using CSS.supports() and adapts layouts accordingly. As foldable devices become more common, implementing these patterns ensures your applications provide optimal experiences across the full range of modern hardware.

Keeping Floating Action Buttons Visible During Zoom

1// Keep a floating action button visible during zoom2const viewport = window.visualViewport;3const fab = document.getElementById('floating-action-button');4 5function positionFloatingButton() {6 const padding = 16; // 16px padding from edges7 const bottomOffset = viewport.height - viewport.offsetTop - padding;8 const rightOffset = viewport.width - viewport.offsetLeft - padding;9 10 fab.style.position = 'fixed';11 fab.style.bottom = `${bottomOffset}px`;12 fab.style.right = `${rightOffset}px`;13}14 15// Update button position on any viewport change16viewport.addEventListener('resize', positionFloatingButton);17viewport.addEventListener('scroll', positionFloatingButton);18viewport.addEventListener('scrollend', positionFloatingButton);19 20// Initial positioning21positionFloatingButton();

Detecting Keyboard Appearance and Adjusting Form Layouts

1// Adjust viewport when keyboard appears/disappears2const viewport = window.visualViewport;3const formContainer = document.getElementById('form-container');4const submitButton = document.getElementById('submit-button');5 6let lastViewportHeight = viewport.height;7 8viewport.addEventListener('resize', () => {9 const currentHeight = viewport.height;10 const heightDiff = lastViewportHeight - currentHeight;11 12 // Detect keyboard: significant height reduction (>100px)13 if (heightDiff > 100) {14 // Keyboard appeared - adjust form scrolling15 formContainer.style.paddingBottom = `${heightDiff + 20}px`;16 17 // Ensure submit button is visible by scrolling to it18 submitButton.scrollIntoView({ behavior: 'smooth', block: 'center' });19 } else if (heightDiff < -100) {20 // Keyboard disappeared - restore normal padding21 formContainer.style.paddingBottom = '';22 }23 24 lastViewportHeight = currentHeight;25});

Zoom-Level-Dependent UI Changes

1// Adapt UI based on zoom level2const viewport = window.visualViewport;3const controlPanel = document.getElementById('map-controls');4 5function updateControlsForZoom() {6 const scale = viewport.scale;7 8 // At low zoom (overview mode), show minimal controls9 if (scale < 1.5) {10 controlPanel.classList.add('overview-mode');11 controlPanel.classList.remove('detail-mode');12 controlPanel.innerHTML = '<button>Zoom In</button>';13 }14 // At high zoom (detail mode), show all controls15 else if (scale >= 1.5) {16 controlPanel.classList.remove('overview-mode');17 controlPanel.classList.add('detail-mode');18 controlPanel.innerHTML = '<button>Zoom In</button><button>Zoom Out</button><button>Reset</button>';19 }20}21 22// Throttle zoom-level updates for performance23let updateTimeout;24viewport.addEventListener('resize', () => {25 clearTimeout(updateTimeout);26 updateTimeout = setTimeout(updateControlsForZoom, 100);27});28 29// Also update on scroll for pinch-zoom scenarios30viewport.addEventListener('scroll', updateControlsForZoom);31 32// Initial call33updateControlsForZoom();

Foldable Device Detection and Layout Adjustment

1// Check for foldable device support and adapt2if (CSS.supports('viewport-segment', 'auto 0 auto 50%')) {3 // Device supports viewport segments4 5 const viewport = window.visualViewport;6 const leftPanel = document.getElementById('left-panel');7 const rightPanel = document.getElementById('right-panel');8 9 function layoutForFoldable() {10 const segs = window.getViewportSegments();11 12 if (segs.length >= 2) {13 // Device is unfolded - two segments available14 leftPanel.classList.add('split-view');15 rightPanel.classList.add('split-view');16 leftPanel.style.flex = '1';17 rightPanel.style.flex = '1';18 } else {19 // Device is folded or not foldable - single viewport20 leftPanel.classList.remove('split-view');21 rightPanel.classList.remove('split-view');22 leftPanel.style.flex = '';23 rightPanel.style.flex = '';24 }25 }26 27 viewport.addEventListener('resize', layoutForFoldable);28 layoutForFoldable();29}

Integration with Modern Frameworks

Using Visual Viewport in React Applications

In React applications, the Visual Viewport API integrates naturally with the component lifecycle and hooks system. A custom hook provides a clean abstraction for viewport tracking that can be reused across components. This approach encapsulates the event listener management, state updates, and cleanup logic in a reusable module.

The useVisualViewport hook demonstrates best practices including proper cleanup of event listeners, handling API unavailability, and providing a consistent state interface for consuming components. The hook returns null until the component mounts on the client side, then provides an object with all viewport properties.

Using Visual Viewport in Next.js Applications

Next.js applications can use the Visual Viewport API with client-side hooks, ensuring compatibility with the framework's hydration model. The API should only be accessed after the component mounts on the client, as window is not available during server-side rendering.

This example shows a sticky header component that adjusts its positioning based on the visual viewport's offset and detects keyboard visibility by monitoring height changes. The header uses offsetTop to position itself correctly even when users scroll while zoomed in, and the keyboard detection enables a compact mode that maximizes available screen space during text input.

For developers working with React, understanding modern API data fetching methods in React complements viewport tracking well, as many applications combine viewport awareness with dynamic data loading based on visible content.

React Custom Hook for Visual Viewport

1import { useState, useEffect, useCallback } from 'react';2 3function useVisualViewport() {4 const [viewport, setViewport] = useState(null);5 6 useEffect(() => {7 if (!window.visualViewport) {8 console.warn('Visual Viewport API not supported');9 return;10 }11 12 const vv = window.visualViewport;13 14 const updateViewport = () => {15 setViewport({16 width: vv.width,17 height: vv.height,18 scale: vv.scale,19 offsetLeft: vv.offsetLeft,20 offsetTop: vv.offsetTop,21 pageLeft: vv.pageLeft,22 pageTop: vv.pageTop23 });24 };25 26 // Initial state capture27 updateViewport();28 29 // Event listeners for all viewport changes30 vv.addEventListener('resize', updateViewport);31 vv.addEventListener('scroll', updateViewport);32 vv.addEventListener('scrollend', updateViewport);33 34 // Cleanup on unmount35 return () => {36 vv.removeEventListener('resize', updateViewport);37 vv.removeEventListener('scroll', updateViewport);38 vv.removeEventListener('scrollend', updateViewport);39 };40 }, []);41 42 return viewport;43}44 45// Usage in a component46function ZoomAwareComponent() {47 const viewport = useVisualViewport();48 49 if (!viewport) {50 return <div>Visual Viewport API not supported</div>;51 }52 53 return (54 <div className="zoom-aware">55 <p>Viewport Width: {viewport.width}px</p>56 <p>Viewport Height: {viewport.height}px</p>57 <p>Zoom Scale: {viewport.scale}x</p>58 <p>Position: {viewport.offsetLeft}, {viewport.offsetTop}</p>59 </div>60 );61}

Next.js Client Component with Keyboard Detection

1'use client';2 3import { useState, useEffect } from 'react';4 5export default function StickyHeader() {6 const [isKeyboardVisible, setIsKeyboardVisible] = useState(false);7 const [viewportHeight, setViewportHeight] = useState(0);8 9 useEffect(() => {10 if (!window.visualViewport) return;11 12 const vv = window.visualViewport;13 const initialHeight = vv.height;14 15 const handleResize = () => {16 setViewportHeight(vv.height);17 18 // Detect keyboard: significant height reduction indicates keyboard19 const heightDiff = initialHeight - vv.height;20 setIsKeyboardVisible(heightDiff > 150);21 };22 23 vv.addEventListener('resize', handleResize);24 25 return () => {26 vv.removeEventListener('resize', handleResize);27 };28 }, []);29 30 return (31 <header32 className={`sticky-header ${isKeyboardVisible ? 'compact' : ''}`}33 style={{34 position: 'fixed',35 top: viewportHeight > 0 ? `${window.visualViewport?.offsetTop || 0}px` : '0',36 transition: 'top 0.2s ease'37 }}38 >39 <nav>40 {/* Navigation content */}41 </nav>42 </header>43 );44}

Best Practices

Performance Optimization

The Visual Viewport events fire frequently during interactions like scrolling and zooming. Unoptimized event handlers can cause janky animations and poor user experiences. Several strategies help maintain smooth performance while responding to viewport changes.

Debouncing and throttling prevent excessive function calls by limiting how often handlers execute. For expensive operations like layout calculations, wait until events settle before executing. The scrollend event is particularly valuable for operations that should only occur after scrolling completes, avoiding the need for manual debouncing.

RequestAnimationFrame synchronizes updates with the browser's rendering cycle, preventing layout thrashing and ensuring smooth visual updates. By queuing updates to run during the next paint opportunity, you avoid forcing multiple layout recalculations in a single frame.

CSS transformations for visual updates avoid triggering layout recalculations, improving performance significantly compared to modifying width, height, or position properties. Use transform: translate() instead of changing top or left values for animated elements.

Feature Detection and Fallbacks

Always verify API availability before use, as older browsers or non-mainstream environments may lack support. Provide graceful degradation that falls back to traditional properties when the API is unavailable. This ensures your applications work across the entire browser landscape while taking advantage of advanced features where supported.

The following pattern demonstrates comprehensive feature detection with fallback logic that maintains functionality across all browsers.

Combining with CSS Viewport Units

The Visual Viewport API complements CSS viewport units (vw, vh, svw, svh) rather than replacing them entirely. CSS units are valuable for initial responsive styling and layout calculations, while the JavaScript API enables dynamic adjustments based on runtime viewport changes like keyboard appearance.

Use CSS viewport units for your baseline responsive design--they provide excellent performance and work without JavaScript. Then layer JavaScript-based adjustments on top for dynamic scenarios that CSS alone cannot handle, such as on-screen keyboard detection and pinch-zoom element repositioning. This hybrid approach gives you the best of both worlds: fast initial rendering with CSS and runtime adaptability with JavaScript.

Throttled Viewport Updates for Performance

1// Throttle function for performance optimization2function throttle(func, limit) {3 let inThrottle;4 return function(...args) {5 if (!inThrottle) {6 func.apply(this, args);7 inThrottle = true;8 setTimeout(() => inThrottle = false, limit);9 }10 };11}12 13// RequestAnimationFrame pattern for smooth updates14let pendingUpdate = false;15 16function scheduleUpdate(callback) {17 if (!pendingUpdate) {18 pendingUpdate = true;19 requestAnimationFrame(() => {20 callback();21 pendingUpdate = false;22 });23 }24}25 26const viewport = window.visualViewport;27 28// Throttled handler for expensive operations29const handleViewportChange = throttle(() => {30 updateComplexLayout();31}, 100);32 33viewport.addEventListener('resize', handleViewportChange);34viewport.addEventListener('scroll', handleViewportChange);35 36// RAF-based handler for smooth visual updates37viewport.addEventListener('scroll', () => {38 scheduleUpdate(() => {39 updateVisualPosition();40 });41});

Feature Detection with Fallback

1// Feature detection helper2function isVisualViewportSupported() {3 return 'visualViewport' in window;4}5 6// Get viewport info with fallback7function getViewportInfo() {8 if (!isVisualViewportSupported()) {9 // Fallback to traditional properties for older browsers10 return {11 width: window.innerWidth,12 height: window.innerHeight,13 scale: 1,14 offsetLeft: window.scrollX,15 offsetTop: window.scrollY,16 source: 'fallback'17 };18 }19 20 const vv = window.visualViewport;21 return {22 width: vv.width,23 height: vv.height,24 scale: vv.scale,25 offsetLeft: vv.offsetLeft,26 offsetTop: vv.offsetTop,27 pageLeft: vv.pageLeft,28 pageTop: vv.pageTop,29 source: 'visual-viewport'30 };31}32 33// Usage with feature-aware logic34const viewportInfo = getViewportInfo();35console.log('Viewport source:', viewportInfo.source);36 37// Adjust behavior based on available API38if (viewportInfo.source === 'visual-viewport') {39 // Use full API capabilities40 setupAdvancedViewportTracking();41} else {42 // Use basic tracking with fallbacks43 setupBasicViewportTracking();44}

Combining CSS Units with JavaScript API

1// CSS for baseline responsive layout (works without JavaScript)2/*3.responsive-element {4 width: 80vw;5 height: 50vh;6 padding: 2vw;7 max-height: 70vh;8}9 10.form-container {11 padding: 2rem;12 min-height: 100vh;13}14*/15 16// JavaScript for dynamic keyboard detection and adjustments17function adjustForKeyboard() {18 const vv = window.visualViewport;19 if (!vv) return;20 21 // If viewport is significantly smaller than window, keyboard is likely active22 const keyboardActive = vv.height < window.innerHeight * 0.6;23 24 if (keyboardActive) {25 document.body.classList.add('keyboard-active');26 // Adjust fixed elements for keyboard27 document.querySelectorAll('.fixed-bottom').forEach(el => {28 el.style.bottom = `${vv.height - vv.offsetTop}px`;29 });30 } else {31 document.body.classList.remove('keyboard-active');32 // Reset to CSS-defined positions33 document.querySelectorAll('.fixed-bottom').forEach(el => {34 el.style.bottom = '';35 });36 }37}38 39// Listen for viewport changes40if (window.visualViewport) {41 window.visualViewport.addEventListener('resize', adjustForKeyboard);42}

Browser Support and Compatibility

The Visual Viewport API has been widely available across major browsers since August 2021, meeting the Baseline criteria for modern web development. This means you can confidently use the API in production applications knowing it will work for the vast majority of users.

Browser	Support Status	Version Added
Chrome	Full support	76 (2019)
Edge	Full support	79 (2020)
Firefox	Full support	63 (2018)
Safari	Full support	13 (2019)
Safari on iOS	Full support	13 (2019)
Samsung Internet	Full support	12.0

Not supported: Internet Explorer and very old mobile browsers.

Feature Detection Strategies

Implement feature detection at the start of your application to determine the available capabilities. The presence check 'visualViewport' in window is the most reliable method for detecting API availability. This approach is more robust than user agent sniffing, which can be inaccurate and requires constant updates as new browser versions release.

Graceful Degradation Approaches

For unsupported browsers, provide fallbacks that use traditional viewport properties. The fallback strategy should maintain core functionality even if advanced features like pinch-zoom tracking are unavailable. Consider the following approaches:

Progressive enhancement: Build your core experience using fallbacks, then layer on advanced Visual Viewport API features when supported. This ensures all users have a functional experience.
Feature-based adaptation: Use the API for advanced scenarios (keyboard detection, zoom tracking) while relying on traditional properties for basic viewport information. This provides the best experience on each platform.
User communication: For critical features that require the API, consider informing users on older browsers that upgrading will improve their experience, without blocking functionality.

As device capabilities continue to expand--with foldable screens, variable viewport sizes, and diverse input methods--the Visual Viewport API provides the foundation for building web applications that adapt gracefully across the entire browser ecosystem.

Conclusion

The Visual Viewport API bridges a critical gap in web development, providing native access to the actual visible area of web pages across the diverse ways users interact with content on modern devices. By tracking pinch-zooming, keyboard overlays, and scroll position at the visual viewport level, developers can create experiences that feel polished and professional.

Understanding the dual viewport concept--layout viewport versus visual viewport--unlocks the ability to build interfaces that adapt to how users actually use their devices. Whether it's keeping floating action buttons visible during zoom, detecting on-screen keyboards for form optimization, or creating zoom-aware interfaces for maps and galleries, the API provides the precise viewport information that traditional properties cannot deliver.

For Next.js and modern React applications, the API integrates smoothly with component lifecycles and client-side rendering patterns. Custom hooks like useVisualViewport encapsulate the complexity, making viewport-aware features accessible throughout your application. Combined with performance optimization techniques like throttling and requestAnimationFrame, the API enables sophisticated viewport-aware features without sacrificing user experience.

As devices continue to evolve--with foldable screens, variable viewport sizes, and diverse input methods--the Visual Viewport API provides the foundation for building web applications that adapt gracefully to whatever comes next. By implementing these patterns today, you ensure your applications provide excellent experiences across the full range of modern devices.

Sources

Build viewport-aware web applications with Digital Thrive

Our team specializes in modern web development using Next.js and React, creating experiences that adapt seamlessly to any device and interaction pattern. From mobile-first responsive layouts to advanced API integrations, we build applications that perform flawlessly across the full range of devices.