Element.scrollIntoViewIfNeeded() — Methode · JavaScript-Referenz

Signatur

Element.prototype.scrollIntoViewIfNeeded(centerIfNeeded)

Beschreibung

scrollIntoViewIfNeeded() prüft, ob das Element im sichtbaren Bereich seines scrollbaren Vorfahren bzw. des Browserfensters liegt. Nur wenn es nicht vollständig sichtbar ist, wird gescrollt. Ist das Element schon zu sehen, passiert nichts. Genau darin liegt der Unterschied zu Element.scrollIntoView(): Diese Methode scrollt immer, auch wenn das Element schon sichtbar ist. Dadurch „springt“ die Seite unnötig.

Typische Einsatzfälle sind die Tastatur-Navigation in Listen (Autovervollständigung, Dateibäume, Auswahl-Listen), das Hervorheben eines Suchtreffers und das Anzeigen eines fehlerhaften Formularfelds. In all diesen Fällen soll die Ansicht ruhig bleiben, solange das Ziel bereits zu sehen ist.

Mit dem optionalen Parameter centerIfNeeded legen Sie fest, wohin gescrollt wird. Bei true (Standardwert) wird das Element mittig im sichtbaren Bereich ausgerichtet. Bei false wird es nur so weit gescrollt, dass es gerade am nächstgelegenen Rand sichtbar wird. Eine Option für weiches Scrollen (behavior: "smooth") gibt es hier nicht.

Die Methode gehört zu keinem Webstandard. Setzen Sie sie deshalb nur mit Feature-Erkennung ein und sehen Sie einen Ersatz über scrollIntoView({ block: "nearest" }) vor.

Parameter

Name	Typ	Default	Beschreibung
$centerIfNeeded	boolean	true	Bei `true` wird das Element mittig im sichtbaren Bereich ausgerichtet, falls gescrollt werden muss. Bei `false` wird es am nächstgelegenen Rand (oben oder unten) ausgerichtet.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode scrollt nur als Nebeneffekt.

Beispiele

Suchtreffer mittig einblenden, aber nur bei Bedarf

const treffer = document.querySelector('.suchtreffer.aktiv');

if (treffer && typeof treffer.scrollIntoViewIfNeeded === 'function') {
  // Nur scrollen, wenn der Treffer nicht sichtbar ist, dann mittig ausrichten
  treffer.scrollIntoViewIfNeeded(true);
}

Tastatur-Navigation in einer Auswahl-Liste

const liste = document.querySelector('#vorschlaege');
let index = 0;

const markiere = (neuerIndex) => {
  const eintraege = liste.querySelectorAll('li');
  eintraege[index]?.classList.remove('aktiv');
  index = Math.max(0, Math.min(neuerIndex, eintraege.length - 1));
  const aktiv = eintraege[index];
  aktiv.classList.add('aktiv');
  // false: nur minimal scrollen, damit die Liste nicht springt
  aktiv.scrollIntoViewIfNeeded?.(false);
};

document.addEventListener('keydown', (e) => {
  if (e.key === 'ArrowDown') markiere(index + 1);
  if (e.key === 'ArrowUp') markiere(index - 1);
});

Browserübergreifende Hilfsfunktion mit Ersatzlösung

const scrolleFallsNoetig = (el, zentrieren = true) => {
  if (typeof el.scrollIntoViewIfNeeded === 'function') {
    el.scrollIntoViewIfNeeded(zentrieren);
    return 'nativ';
  }
  // Ersatz nach Standard: 'nearest' scrollt nur, wenn nötig
  el.scrollIntoView({ block: 'nearest', inline: 'nearest' });
  return 'fallback';
};

const feld = document.querySelector('input:invalid');
if (feld) {
  console.log(scrolleFallsNoetig(feld, false));
  feld.focus({ preventScroll: true });
}

nativ // in Chrome/Safari fallback // in Firefox

// Wichtig · Fallstricke

Nicht standardisiert: Chromium-Browser und Safari unterstützen die Methode, Firefox nicht. Prüfen Sie deshalb immer vor dem Aufruf, ob sie existiert (typeof el.scrollIntoViewIfNeeded === 'function' oder den Operator ?.()). Sonst entsteht ein TypeError.
Standardkonformer Ersatz: el.scrollIntoView({ block: 'nearest', inline: 'nearest' }) verhält sich fast wie scrollIntoViewIfNeeded(false). Ein echtes Gegenstück zu „nur bei Bedarf und dann mittig“ gibt es nicht. Dafür können Sie die Sichtbarkeit selbst mit getBoundingClientRect() oder einem IntersectionObserver prüfen und danach scrollIntoView({ block: 'center' }) aufrufen.
Kein weiches Scrollen: Die Methode kennt keine behavior-Option. Die CSS-Eigenschaft scroll-behavior: smooth am Scroll-Container kann trotzdem wirken, je nach Browser.
Auch verschachtelte scrollbare Vorfahren werden gescrollt, nicht nur das Fenster. Wenn das Element display: none hat oder nicht im DOM hängt, passiert nichts.
Rufen Sie die Methode nicht in schnellen Schleifen auf (z. B. bei jedem scroll-Event). Die Layout-Berechnung kann ein erzwungenes Reflow auslösen.

Siehe auch

Element.scrollIntoView() Element.getBoundingClientRect() Element.scrollTo() Window.scrollTo() IntersectionObserver Element.scrollTop