</> programmierung.net
Start · Sprachen · JavaScript · Referenz · Element.animate()

Element.animate()

Methode

Erstellt eine neue <code>Animation</code> aus Keyframes und Zeitoptionen, wendet sie auf das Element an und startet sie sofort.

seit JavaScript Web Animations API – Baseline: alle modernen Brows Kategorie: webapi

Signatur

Element.prototype.animate(keyframes, options)

Beschreibung

Element.animate() ist der einfachste Einstieg in die Web Animations API. Mit einem Aufruf wird ein KeyframeEffect erzeugt, in ein Animation-Objekt verpackt, an das Element gebunden und abgespielt. Das Ergebnis ist vergleichbar mit einer CSS-Animation, wird aber vollständig per JavaScript gesteuert – ohne @keyframes-Regeln im Stylesheet.

Die Methode eignet sich besonders für dynamische Animationen, deren Werte erst zur Laufzeit feststehen (z. B. Positionen aus Mausereignissen, berechnete Höhen), sowie für Animationen, die pausiert, umgekehrt, beschleunigt oder abgebrochen werden sollen. Über das zurückgegebene Animation-Objekt stehen play(), pause(), reverse(), cancel(), finish(), playbackRate und das Promise finished zur Verfügung.

Keyframes können als Array von Objekten ([{ opacity: 0 }, { opacity: 1 }]) oder als Objekt mit Werte-Arrays ({ opacity: [0, 1] }) angegeben werden. CSS-Eigenschaften werden in camelCase geschrieben (backgroundColor); offset, easing und composite sind spezielle Keyframe-Schlüssel.

Wichtig: Nach Ende der Animation kehrt das Element standardmäßig in seinen ursprünglichen Stil zurück. Soll der Endzustand erhalten bleiben, nutzt man fill: "forwards" oder – sauberer – setzt den Endwert nach animation.finished direkt per Stil bzw. mit commitStyles().

Parameter

Name Typ Default Beschreibung
$keyframes Pflicht Array<Object> | Object | null Keyframes als Array von Stil-Objekten oder als Objekt mit Werte-Arrays pro Eigenschaft. Optionale Schlüssel: offset (0–1), easing, composite. null erzeugt eine Animation ohne Keyframes.
$options number | Object Entweder die Dauer in Millisekunden oder ein Objekt mit Zeitangaben: duration, delay, endDelay, iterations (auch Infinity), direction ("normal", "reverse", "alternate", "alternate-reverse"), easing, fill ("none", "forwards", "backwards", "both"), iterationStart, composite, iterationComposite, id, pseudoElement (z. B. "::before") sowie timeline (z. B. eine ScrollTimeline).

Rückgabewert

Typ
Animation
Beschreibung
Das bereits laufende Animation-Objekt, über das die Wiedergabe gesteuert und das Ende per animation.finished (Promise) abgewartet werden kann.

Beispiele

Einfaches Einblenden mit Dauer als Zahl

const box = document.querySelector('.box');

// Dauer direkt als Zahl (Millisekunden)
box.animate(
  [
    { opacity: 0, transform: 'translateY(20px)' },
    { opacity: 1, transform: 'translateY(0)' }
  ],
  400
);

Endlos pulsierender Button mit Optionen-Objekt

const button = document.querySelector('#cta');

const pulse = button.animate(
  { transform: ['scale(1)', 'scale(1.08)', 'scale(1)'] },
  {
    duration: 1200,
    iterations: Infinity,
    easing: 'ease-in-out'
  }
);

// Beim Hover pausieren, danach weiterlaufen lassen
button.addEventListener('mouseenter', () => pulse.pause());
button.addEventListener('mouseleave', () => pulse.play());

Element ausblenden und danach entfernen

const removeWithFade = async (el) => {
  const anim = el.animate(
    [{ opacity: 1, height: `${el.offsetHeight}px` }, { opacity: 0, height: '0px' }],
    { duration: 300, easing: 'ease-out', fill: 'forwards' }
  );
  await anim.finished;
  el.remove();
  console.log('Element entfernt');
};

document.querySelectorAll('.notice .close').forEach((btn) => {
  btn.addEventListener('click', () => removeWithFade(btn.closest('.notice')));
});
Element entfernt

Endzustand übernehmen und Bewegungsreduktion respektieren

const panel = document.querySelector('.panel');
const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;

const anim = panel.animate(
  [{ transform: 'translateX(-100%)' }, { transform: 'translateX(0)' }],
  { duration: reduceMotion ? 0 : 500, easing: 'cubic-bezier(.2,.8,.2,1)', fill: 'forwards' }
);

anim.finished.then(() => {
  anim.commitStyles(); // Endwert in style-Attribut schreiben
  anim.cancel();       // Animation freigeben
  console.log(panel.style.transform);
});
translateX(0px)

// Wichtig · Fallstricke

  • Stil wird zurückgesetzt: Ohne fill: "forwards" springt das Element nach Ende in den Ausgangszustand zurück. Viele dauerhaft gefüllte Animationen kosten Speicher; Browser entfernen ersetzte Fill-Animationen automatisch (Ereignis remove). Besser: commitStyles() + cancel().
  • camelCase statt Bindestrich: backgroundColor statt background-color; float heißt cssFloat, offset muss als cssOffset geschrieben werden, da offset ein Keyframe-Schlüssel ist.
  • Performance: Nur transform und opacity werden zuverlässig auf dem Compositor animiert. Eigenschaften wie width, height oder top lösen Layout aus und können ruckeln.
  • Abgebrochene Animationen: Wird cancel() aufgerufen, wird animation.finished mit einem AbortError abgelehnt – beim await ggf. mit try/catch absichern.
  • Kompatibilität: Grundfunktion in allen modernen Browsern (Chrome 36+, Firefox 48+, Safari 13.1+). Optionen wie composite, pseudoElement, commitStyles() sind jünger; timeline mit ScrollTimeline/ViewTimeline wird noch nicht überall unterstützt. Einfache Easing-Werte wie linear() ggf. prüfen.
  • Barrierefreiheit: prefers-reduced-motion berücksichtigen und Bewegungen für betroffene Nutzer reduzieren.

Siehe auch

Animation Animation.finished Animation.cancel() Element.after() Element.remove()
← Vorheriger Eintrag Element.after()