VirtualKeyboard.overlaysContent — Eigenschaft · JavaScript-Referenz

Signatur

navigator.virtualKeyboard.overlaysContent

Beschreibung

Standardmäßig verkleinern Browser auf Geräten mit Bildschirmtastatur (Smartphones, Tablets, Touch-Laptops) den Layout- oder visuellen Viewport, sobald die Tastatur eingeblendet wird. Dadurch bleibt das fokussierte Eingabefeld sichtbar, das Layout kann dabei aber unerwartet springen oder neu umbrechen.

Setzt du navigator.virtualKeyboard.overlaysContent = true, schaltest du dieses automatische Verhalten ab: Die Tastatur legt sich über den Inhalt, der Viewport behält seine Größe. Ab dann bist du selbst für das Layout zuständig. Dafür liefert die API die Tastaturgeometrie über navigator.virtualKeyboard.boundingRect, das Ereignis geometrychange und die CSS-Umgebungsvariablen env(keyboard-inset-top), env(keyboard-inset-height), env(keyboard-inset-bottom) usw.

Einsatzbereiche sind z. B. Chat-Apps mit fest angedockter Eingabezeile, Vollbild-Editoren, Spiele oder Kartenanwendungen, bei denen ein automatisches Verkleinern stören würde. Die Eigenschaft ist lesbar und beschreibbar. Der Standardwert ist false.

Beispiele

Overlay-Modus mit Feature-Erkennung aktivieren

if ('virtualKeyboard' in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;
  console.log('Overlay aktiv:', navigator.virtualKeyboard.overlaysContent);
} else {
  console.log('VirtualKeyboard API nicht verfügbar – Browser passt Viewport selbst an.');
}

Overlay aktiv: true

Chat-Eingabezeile über der Tastatur halten (JS + geometrychange)

const composer = document.querySelector('#composer');

if ('virtualKeyboard' in navigator) {
  const vk = navigator.virtualKeyboard;
  vk.overlaysContent = true;

  vk.addEventListener('geometrychange', (event) => {
    const { height } = event.target.boundingRect;
    // Eingabezeile um die Tastaturhöhe nach oben schieben
    composer.style.transform = `translateY(-${height}px)`;
    console.log(`Tastaturhöhe: ${height}px`);
  });
}

Tastaturhöhe: 312px

Layout rein per CSS-Umgebungsvariablen anpassen

// JS: nur Overlay-Modus aktivieren
if ('virtualKeyboard' in navigator) {
  navigator.virtualKeyboard.overlaysContent = true;
}

// CSS dynamisch einfügen: Grid-Zeile reserviert Platz für die Tastatur
const style = document.createElement('style');
style.textContent = `
  body {
    display: grid;
    grid-template-rows: 1fr auto env(keyboard-inset-height, 0px);
    height: 100dvh;
    margin: 0;
  }
`;
document.head.append(style);

Overlay nur für einen Editor temporär einschalten

const editor = document.querySelector('#editor');

editor.addEventListener('focus', () => {
  if ('virtualKeyboard' in navigator) navigator.virtualKeyboard.overlaysContent = true;
});

editor.addEventListener('blur', () => {
  if ('virtualKeyboard' in navigator) navigator.virtualKeyboard.overlaysContent = false;
});

// Wichtig · Fallstricke

Experimentell und nur in Chromium: Chrome, Edge und Opera ab Version 94 unterstützen die API, Firefox und Safari (inklusive iOS) nicht. Frag deshalb immer vorher mit 'virtualKeyboard' in navigator ab, ob sie verfügbar ist.
Sicherer Kontext: Die API steht nur über HTTPS (oder localhost) zur Verfügung und nur im obersten Browsing-Kontext, nicht in Cross-Origin-iframes.
Die Verantwortung liegt bei dir: Bei true scrollt der Browser das fokussierte Feld nicht mehr automatisch in den sichtbaren Bereich. Ohne eigene Anpassung werden Eingabefelder von der Tastatur verdeckt, was die Barrierefreiheit und die Bedienbarkeit verschlechtert.
Auf Geräten ohne Bildschirmtastatur (klassischer Desktop) hat die Eigenschaft keine sichtbare Wirkung. boundingRect bleibt dort ein leeres Rechteck (alle Werte 0).
Die CSS-Variablen env(keyboard-inset-*) sind erst gesetzt, wenn overlaysContent auf true steht. Gib immer einen Ersatzwert an, z. B. env(keyboard-inset-height, 0px).
Es gibt Alternativen, die in mehr Browsern funktionieren: die Visual Viewport API (window.visualViewport, resize-Ereignis) oder das Meta-Tag <meta name=\"viewport\" content=\"interactive-widget=overlays-content\">.

Siehe auch

VirtualKeyboard.boundingRect KeyboardEvent.code HTMLMetaElement.content HTMLTemplateElement.content KeyboardEvent.isComposing