Element.checkVisibility() — Methode · JavaScript-Referenz

Signatur

Element.prototype.checkVisibility(options)

Beschreibung

checkVisibility() beantwortet die Frage „Könnte dieses Element überhaupt zu sehen sein?“ mit einem einzigen Methodenaufruf. Der Browser wertet dafür die berechneten Stile des Elements und aller seiner Vorfahren aus, auch über Shadow-DOM-Grenzen hinweg. Bisher brauchte man dafür Behelfslösungen wie el.offsetParent !== null oder getComputedStyle() in einer Schleife über alle Vorfahren.

Ohne Optionen gibt die Methode false zurück, wenn das Element keine Layout-Box hat (zum Beispiel wegen display: none am Element oder an einem Vorfahren, bei display: contents oder wenn das Element nicht im Dokument hängt) oder wenn ein Vorfahre content-visibility: hidden hat. In allen anderen Fällen ist das Ergebnis true.

Über das Optionsobjekt kannst du zusätzliche Prüfungen einschalten: opacity: 0, visibility: hidden/collapse und Inhalte, die wegen content-visibility: auto gerade nicht gerendert werden. Typische Einsatzfälle sind: das erste sichtbare Formularfeld fokussieren, versteckte Elemente bei der Validierung überspringen, Tastaturnavigation in Menüs oder die Prüfung von Tracking-/Analyse-Elementen.

Wichtig: „potenziell sichtbar“ bedeutet nicht, dass das Element im Viewport liegt oder nicht verdeckt ist. Die Methode kümmert sich weder um die Scrollposition noch um Überlagerungen, overflow-Beschneidung oder eine Größe von 0×0 Pixeln.

Parameter

Name	Typ	Default	Beschreibung
$options	Object	{}	Optionales Objekt, das zusätzliche Sichtbarkeitsprüfungen einschaltet. Alle Eigenschaften sind standardmäßig `false`.
$options.opacityProperty	boolean	false	Bei `true` ist das Ergebnis `false`, wenn das Element oder ein Vorfahre `opacity: 0` hat. Alter Name: `checkOpacity`.
$options.visibilityProperty	boolean	false	Bei `true` ist das Ergebnis `false`, wenn der berechnete Wert von `visibility` `hidden` oder `collapse` ist. Alter Name: `checkVisibilityCSS`.
$options.contentVisibilityAuto	boolean	false	Bei `true` ist das Ergebnis `false`, wenn ein Vorfahre `content-visibility: auto` hat und das Rendern seiner Inhalte gerade übersprungen wird.
$options.checkOpacity	boolean	false	Veralteter Alias für `opacityProperty`, der aus Kompatibilitätsgründen weiter unterstützt wird.
$options.checkVisibilityCSS	boolean	false	Veralteter Alias für `visibilityProperty`, der aus Kompatibilitätsgründen weiter unterstützt wird.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn das Element nach den gewählten Kriterien potenziell sichtbar ist, sonst false.

Beispiele

Einfache Prüfung auf display: none

// HTML: <div id="panel" style="display: none"><p id="text">Hallo</p></div>
const panel = document.querySelector('#panel');
const text = document.querySelector('#text');

console.log(panel.checkVisibility()); // Element selbst ist ausgeblendet
console.log(text.checkVisibility());  // Vorfahre ist ausgeblendet

panel.style.display = 'block';
console.log(text.checkVisibility());

false false true

Zusätzliche Prüfung von opacity und visibility

// HTML: <button id="btn" style="visibility: hidden">Senden</button>
const btn = document.querySelector('#btn');

// Ohne Optionen zählt visibility: hidden als sichtbar (die Box existiert)
console.log(btn.checkVisibility());

console.log(btn.checkVisibility({
  opacityProperty: true,
  visibilityProperty: true
}));

true false

Erstes sichtbares ungültiges Formularfeld fokussieren

const focusFirstInvalid = (form) => {
  const fields = [...form.querySelectorAll('input, select, textarea')];
  const target = fields.find((field) =>
    !field.validity.valid &&
    field.checkVisibility({ visibilityProperty: true, opacityProperty: true })
  );
  target?.focus();
  return target ?? null;
};

document.querySelector('form').addEventListener('submit', (event) => {
  if (!event.target.checkValidity()) {
    event.preventDefault();
    const field = focusFirstInvalid(event.target);
    console.log('Fokus auf:', field?.name);
  }
});

Fokus auf: email

Feature-Erkennung mit Fallback für ältere Browser

const isVisible = (el) => {
  if (typeof el.checkVisibility === 'function') {
    return el.checkVisibility({ visibilityProperty: true });
  }
  // Fallback: getClientRects() ist leer, wenn keine Layout-Box existiert
  return el.getClientRects().length > 0 &&
    getComputedStyle(el).visibility !== 'hidden';
};

console.log(isVisible(document.body));

true

// Wichtig · Fallstricke

Nicht gleich „im Viewport“: Liegt ein Element außerhalb des sichtbaren Bereichs, wird es durch overflow: hidden abgeschnitten, von einem anderen Element verdeckt oder ist es 0×0 Pixel groß, liefert die Methode trotzdem true. Für die Sichtbarkeit im Viewport nimmst du IntersectionObserver.
Standardverhalten: Ohne Optionen werden visibility: hidden und opacity: 0 nicht berücksichtigt. Diese Prüfungen musst du ausdrücklich einschalten.
display: contents liefert false, weil das Element selbst keine Box erzeugt, obwohl seine Kindelemente sichtbar sein können.
Performance: Der Aufruf kann eine Neuberechnung von Stilen und Layout erzwingen. Häufige Aufrufe in Schleifen, abwechselnd mit DOM-Änderungen, können Layout-Thrashing verursachen. Lies deshalb möglichst alle Werte gebündelt aus.
Kompatibilität: Die Methode ist seit März 2024 Baseline (Safari 17.4). Die Optionsnamen opacityProperty und visibilityProperty gibt es erst ab Chrome 121 und Firefox 122. Ältere Versionen kennen nur checkOpacity und checkVisibilityCSS. Für breite Unterstützung kannst du beide Namen gleichzeitig übergeben. In älteren Browsern brauchst du eine Feature-Erkennung.
Bei Elementen, die nicht im Dokument hängen, ist das Ergebnis immer false.

Siehe auch

Window.getComputedStyle() Element.getClientRects() Element.getBoundingClientRect() IntersectionObserver HTMLElement.offsetParent HTMLElement.hidden ElementInternals.checkValidity()