Window.setTimeout() — Methode · JavaScript-Referenz

Signatur

Window.setTimeout(functionRef, delay, ...args)

Beschreibung

setTimeout() plant die einmalige Ausführung einer Funktion nach einer Mindestverzögerung ein. Der Aufruf blockiert nicht: Die Methode gibt sofort eine Timer-ID zurück, und der Callback wird später als Task in die Ereignisschleife (Event Loop) eingereiht.

Typische Einsatzzwecke sind verzögerte UI-Aktionen (z. B. Hinweise nach einigen Sekunden ausblenden), Debouncing von Eingaben, Zeitlimits für asynchrone Operationen oder das Aufteilen langer Berechnungen in kleinere Stücke, damit der Browser zwischendurch neu zeichnen kann.

Die Verzögerung ist ein Minimum, keine Garantie: Läuft gerade anderer Code, wartet der Callback, bis der Aufrufstapel leer ist. Mit der zurückgegebenen ID lässt sich der Timer über clearTimeout() vor Ablauf abbrechen. Für wiederholte Ausführung gibt es setInterval() oder rekursive setTimeout()-Aufrufe.

Parameter

Name	Typ	Default	Beschreibung
$functionRef Pflicht	Function \| string		Die auszuführende Funktion. Alternativ ein Code-String, der wie bei `eval()` ausgewertet wird – davon ist dringend abzuraten.
$delay	number	0	Verzögerung in Millisekunden. Nicht-numerische oder negative Werte werden als `0` behandelt. Werte über 2³¹−1 (ca. 24,8 Tage) laufen über und führen zu sofortiger Ausführung.
$...args	any		Zusätzliche Argumente, die beim Ablauf an `functionRef` übergeben werden.

Rückgabewert

Typ

number

Beschreibung

Eine positive Ganzzahl (Timer-ID), die an clearTimeout() übergeben werden kann. In Node.js wird stattdessen ein Timeout-Objekt zurückgegeben.

Beispiele

Hinweis nach 3 Sekunden ausblenden

const toast = document.querySelector('#toast');
toast.hidden = false;

setTimeout(() => {
  toast.hidden = true;
  console.log('Toast ausgeblendet');
}, 3000);

Toast ausgeblendet (nach ca. 3 s)

Argumente übergeben und Timer abbrechen

const greet = (name, greeting) => console.log(`${greeting}, ${name}!`);

const id = setTimeout(greet, 1000, 'Anna', 'Hallo');

// Benutzer bricht ab, bevor der Timer abläuft
document.querySelector('#cancel').addEventListener('click', () => {
  clearTimeout(id);
  console.log('Begrüßung abgebrochen');
});

Hallo, Anna! (sofern nicht abgebrochen)

Debounce für Sucheingaben

const debounce = (fn, wait = 300) => {
  let timerId;
  return (...args) => {
    clearTimeout(timerId);
    timerId = setTimeout(() => fn(...args), wait);
  };
};

const search = debounce((query) => console.log('Suche nach:', query), 400);

document.querySelector('#search').addEventListener('input', (e) => search(e.target.value));

Suche nach: javascript (erst 400 ms nach dem letzten Tastendruck)

Promise-basierte Wartefunktion mit Zeitlimit

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

const withTimeout = (promise, ms) =>
  Promise.race([
    promise,
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error(`Zeitüberschreitung nach ${ms} ms`)), ms)
    ),
  ]);

const run = async () => {
  await sleep(500);
  console.log('500 ms gewartet');
  try {
    await withTimeout(sleep(2000), 1000);
  } catch (err) {
    console.log(err.message);
  }
};

run();

500 ms gewartet Zeitüberschreitung nach 1000 ms

// Wichtig · Fallstricke

Keine exakte Zeit: Der Callback läuft frühestens nach delay ms. Ab der 5. verschachtelten Ebene erzwingen Browser mindestens 4 ms; in inaktiven Tabs werden Timer oft auf ≥ 1 s gedrosselt (bei Hintergrund-Tabs in Chrome teils nur einmal pro Minute).
setTimeout(fn, 0) läuft nach allen bereits eingereihten Microtasks (z. B. Promise.then). Für Microtasks besser queueMicrotask() verwenden.
this-Problem: Wird eine Methode wie setTimeout(obj.method, 100) übergeben, geht der Kontext verloren. Abhilfe: Pfeilfunktion () => obj.method() oder obj.method.bind(obj).
Häufiger Fehler: setTimeout(fn(), 1000) ruft fn sofort auf und übergibt deren Rückgabewert – richtig ist setTimeout(fn, 1000).
Sicherheit: Code-Strings werden wie eval() ausgewertet, sind anfällig für XSS und werden durch CSP ohne 'unsafe-eval' blockiert. Immer Funktionen übergeben.
Überlauf: Verzögerungen größer als 2147483647 ms werden als 32-Bit-Wert interpretiert und laufen sofort ab.
Timer-IDs werden von setTimeout() und setInterval() gemeinsam vergeben; sie sind vielleicht austauschbar, sollten aber immer mit der passenden clear…-Funktion gelöscht werden.

Siehe auch

Window.clearTimeout() Window.setInterval() Window.clearInterval() Window.requestAnimationFrame() Window.queueMicrotask() Window.requestIdleCallback() Promise