VisualViewport.width — Eigenschaft · JavaScript-Referenz

Signatur

VisualViewport.width

Beschreibung

window.visualViewport.width gibt an, wie breit der aktuell sichtbare Bereich der Seite in CSS-Pixeln ist. Anders als der Layout-Viewport (window.innerWidth bzw. document.documentElement.clientWidth) berücksichtigt der visuelle Viewport das Pinch-Zoom des Nutzers: Zoomt man auf einem Mobilgerät zweifach hinein, halbiert sich width ungefähr, während der Layout-Viewport unverändert bleibt.

Die Eigenschaft ist nützlich, wenn Elemente am tatsächlich sichtbaren Bildschirmausschnitt ausgerichtet werden sollen – etwa schwebende Werkzeugleisten, Kontextmenüs, Tooltips oder fixierte Bedienelemente, die beim Zoomen nicht aus dem Bild wandern dürfen. Zusammen mit offsetLeft, offsetTop, height und scale lässt sich die exakte Lage des sichtbaren Bereichs bestimmen.

Der Wert schließt Scrollleisten aus und ist ein Gleitkommawert (z. B. 392.7272644042969). Da er sich bei Zoom, Drehen des Geräts oder Ein-/Ausblenden der Bildschirmtastatur ändern kann, sollte man ihn nicht einmalig zwischenspeichern, sondern auf das resize-Ereignis von visualViewport reagieren.

Rückgabewert

Typ

number

Beschreibung

Breite des visuellen Viewports in CSS-Pixeln (Gleitkommazahl, ohne Scrollleisten). 0, wenn das zugehörige Dokument nicht vollständig aktiv ist (z. B. in einem entfernten iframe).

Beispiele

Breite von visuellem und Layout-Viewport vergleichen

const vv = window.visualViewport;

if (vv) {
  console.log(`Visueller Viewport: ${vv.width.toFixed(1)} px`);
  console.log(`Layout-Viewport:    ${document.documentElement.clientWidth} px`);
  console.log(`Zoomfaktor:         ${vv.scale}`);
} else {
  console.log('VisualViewport API nicht verfügbar');
}

Visueller Viewport: 196.4 px Layout-Viewport: 393 px Zoomfaktor: 2

Werkzeugleiste beim Pinch-Zoom sichtbar halten

const toolbar = document.querySelector('#toolbar');
const vv = window.visualViewport;

const positionToolbar = () => {
  // Leiste immer am unteren Rand des sichtbaren Bereichs, volle sichtbare Breite
  toolbar.style.width = `${vv.width}px`;
  toolbar.style.transform =
    `translate(${vv.offsetLeft}px, ${vv.offsetTop + vv.height - toolbar.offsetHeight}px)`;
};

vv.addEventListener('resize', positionToolbar);
vv.addEventListener('scroll', positionToolbar);
positionToolbar();

Kompakte Ansicht bei schmalem sichtbarem Bereich

const vv = window.visualViewport;

const updateLayout = () => {
  const compact = vv.width < 360;
  document.body.classList.toggle('compact', compact);
  console.log(`Breite ${Math.round(vv.width)} px → compact: ${compact}`);
};

vv?.addEventListener('resize', updateLayout);
if (vv) updateLayout();

Breite 393 px → compact: false

// Wichtig · Fallstricke

Existenz prüfen: window.visualViewport kann in älteren Browsern undefined sein – vor dem Zugriff prüfen (window.visualViewport?.width).
Wert 0: Ist das Dokument nicht vollständig aktiv (z. B. Referenz auf das visualViewport eines entfernten iframes), liefert die Eigenschaft 0. Nicht als gültige Breite weiterverwenden, sonst drohen Division durch null oder unsichtbare Elemente.
Gleitkommawerte: Der Wert ist oft nicht ganzzahlig; für Vergleiche ggf. runden.
Scrollleisten: Nicht enthalten – der Wert kann daher kleiner als window.innerWidth sein, auch ohne Zoom.
Browser-Zoom vs. Pinch-Zoom: Nur Pinch-Zoom verkleinert den visuellen Viewport relativ zum Layout-Viewport; Desktop-Zoom (Strg +/−) ändert die CSS-Pixelgröße beider Viewports.
Performance: resize- und scroll-Ereignisse feuern häufig; aufwendige Layout-Änderungen per requestAnimationFrame bündeln und transform statt top/left verwenden.
Schreibgeschützt: Zuweisungen werden ignoriert (im Strict Mode ohne Fehler, da nur ein Getter existiert).

Siehe auch

VisualViewport VisualViewport.height VisualViewport.scale VisualViewport.offsetLeft Window.innerWidth PictureInPictureWindow.width