Window: blur — Ereignis · JavaScript-Referenz

Signatur

window.addEventListener("blur", handler)

Beschreibung

Das blur-Event am Window-Objekt wird ausgelöst, wenn das Browserfenster oder das Dokument den Tastaturfokus verliert. Das passiert zum Beispiel, wenn der Nutzer in ein anderes Programm wechselt, in die Adressleiste klickt, ein anderes Fenster öffnet oder in ein <iframe> klickt. Das Gegenstück ist das focus-Event.

Man registriert den Handler mit window.addEventListener("blur", handler) oder über die Eigenschaft window.onblur = handler. Der Handler bekommt ein FocusEvent. Das Event steigt nicht auf (bubbles: false) und lässt sich nicht abbrechen.

Typische Einsatzfälle sind: Animationen oder Spiele pausieren, Polling drosseln, ungesicherte Formulareingaben zwischenspeichern oder Tastenzustände zurücksetzen, weil nach einem Fokuswechsel kein keyup mehr ankommt. Ob der Tab tatsächlich unsichtbar ist, erkennt man damit nicht zuverlässig. Dafür ist die Page Visibility API mit visibilitychange gedacht.

Wichtig: Das blur-Event einzelner Elemente (etwa von Eingabefeldern) steigt nicht bis zu window auf. Ein Listener am Window reagiert deshalb nur auf den Fokusverlust des Fensters selbst, außer man registriert ihn in der Capture-Phase.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Event-Name, hier `"blur"`.
$handler Pflicht	(event: FocusEvent) => void		Callback, der beim Fokusverlust aufgerufen wird. `event.relatedTarget` ist beim Window meist `null`.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `{ once: true }`, `{ capture: true }` oder `{ signal }` zum späteren Entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt undefined zurück. Der Handler bekommt ein FocusEvent-Objekt.

Beispiele

Spiel pausieren, wenn das Fenster den Fokus verliert

let paused = false;

const onBlur = () => {
  paused = true;
  document.title = '⏸ Pausiert';
  console.log('Fenster hat den Fokus verloren – Spiel pausiert');
};

const onFocus = () => {
  paused = false;
  document.title = 'Spiel läuft';
  console.log('Fenster wieder aktiv');
};

window.addEventListener('blur', onBlur);
window.addEventListener('focus', onFocus);

Fenster hat den Fokus verloren – Spiel pausiert

Gedrückte Tasten zurücksetzen (hängende Tasten vermeiden)

const pressed = new Set();

window.addEventListener('keydown', (e) => pressed.add(e.key));
window.addEventListener('keyup', (e) => pressed.delete(e.key));

// Nach einem Fokuswechsel (z. B. Alt+Tab) kommt kein keyup mehr an
window.addEventListener('blur', () => {
  pressed.clear();
  console.log('Tastenzustand zurückgesetzt');
});

Tastenzustand zurückgesetzt

on-Property und Entfernen per AbortController

// Variante 1: on-Property (nur ein Handler möglich)
window.onblur = () => console.log('blur via onblur');

// Variante 2: addEventListener mit AbortSignal
const controller = new AbortController();
window.addEventListener(
  'blur',
  () => console.log('blur via addEventListener'),
  { signal: controller.signal }
);

// Später beide Handler entfernen
setTimeout(() => {
  controller.abort();
  window.onblur = null;
  console.log('blur-Handler entfernt');
}, 10000);

blur via onblur blur via addEventListener

Formularentwurf beim Fokusverlust speichern

const textarea = document.querySelector('#entwurf');

const saveDraft = () => {
  localStorage.setItem('entwurf', textarea?.value ?? '');
  console.log('Entwurf gespeichert');
};

window.addEventListener('blur', saveDraft);

// Zusätzlich für Tab-Wechsel oder Schließen auf Mobilgeräten
document.addEventListener('visibilitychange', () => {
  if (document.visibilityState === 'hidden') saveDraft();
});

Entwurf gespeichert

// Wichtig · Fallstricke

Kein Aufsteigen: blur steigt nicht auf. Fokusverluste von Elementen erreichen einen normalen Window-Listener nicht. Für Elemente nimmt man focusout (steigt auf) oder registriert mit { capture: true }. Dann muss man aber per event.target === window unterscheiden.
iframes: Ein Klick in ein <iframe> löst blur am übergeordneten Window aus, obwohl die Seite sichtbar und aktiv bleibt.
Kein Sichtbarkeitsersatz: Um zu erkennen, ob der Tab im Hintergrund liegt, ist visibilitychange zuverlässiger, vor allem auf Mobilgeräten, wo blur nicht immer ausgelöst wird.
Kein alert() im Handler: alert() oder window.focus() im blur-Handler können zu Fokusschleifen führen und stören die Bedienung.
DevTools: Ein Klick in die Entwicklerwerkzeuge löst ebenfalls blur aus. Das kann beim Debuggen verwirren.
Kompatibilität: Wird von allen Browsern unterstützt. window.onblur erlaubt nur einen Handler, addEventListener dagegen mehrere.

Siehe auch

FocusEvent Document.prototype.hasFocus() EventTarget.prototype.addEventListener() Window: error Window: focus Window: storage