Reanimated 4: CSS-Animations-API Guide

Aktualisiert: 25. Juni 2026

Reanimated 4 ist die erste Hauptversion von react-native-reanimated, die ausschließlich auf der New Architecture (Fabric) läuft und eine deklarative CSS-Animations-API einführt, mit der sich Übergänge und Keyframes ohne useAnimatedStyle beschreiben lassen. Die Bibliothek bleibt im UI-Thread und über 60fps, der Migrationsaufwand aus Reanimated 3 ist aber realer als die Release Notes vermuten lassen. Ich habe Reanimated 4 in den letzten Monaten in zwei produktiven Apps eingeführt (eine Expo-App, eine Bare-RN-App), und teile hier den Pfad, den ich heute wieder gehen würde. Ehrlich gesagt habe ich beim ersten Upgrade an einer Stelle eine ganze Stunde verloren, weil ich das Babel-Plugin doppelt registriert hatte. Dazu unten mehr.

Reanimated 4 benötigt zwingend die New Architecture (Fabric); die Legacy-Bridge wird nicht mehr unterstützt.
Die neue CSS-Animations-API erlaubt es, Übergänge und Keyframes direkt im Style-Objekt zu schreiben, ohne Worklets und useSharedValue.
Worklets sind in das eigenständige Paket react-native-worklets ausgelagert und müssen ab Reanimated 4 separat installiert werden.
Das klassische API (useSharedValue, useAnimatedStyle, withSpring) bleibt erhalten und ist mit der CSS-API mischbar.
Shared Element Transitions via sharedTransitionTag funktionieren in v4 nur mit Fabric und benötigen Expo Router v5 oder React Navigation 7.
Der Bundle-Size-Overhead steigt um ~30 KB, dafür entfallen zwei manuelle Babel-Konfigurationen.

Was ist Reanimated 4?

Reanimated 4 ist die im Mai 2026 veröffentlichte Hauptversion von react-native-reanimated, die zwei strukturelle Änderungen mitbringt: eine deklarative CSS-Animations-API und die Auslagerung der Worklet-Runtime in ein eigenständiges Paket react-native-worklets. Anders als der Sprung von v2 auf v3 ist v4 keine reine API-Erweiterung, sondern setzt die New Architecture mit Fabric-Renderer und TurboModules voraus. Apps auf der alten Bridge können nicht auf v4 aktualisieren. Das ist die wichtigste Compatibility-Information, die man vor der Migration kennen muss.

Der Kerngedanke hinter der CSS-API: Viele Animationen sind so simpel, dass das volle Shared-Value-Plus-Worklet-Modell überdimensioniert wirkt. Ein einfaches Einblenden, ein Skalieren bei Hover oder ein Übergang zwischen zwei Größen lässt sich in v4 als reines Style-Objekt schreiben. Das Software-Mansion-Team beschreibt diesen Ansatz im offiziellen Reanimated-Dokumentationsportal als ergänzend, nicht ersetzend. Die klassische imperative API existiert weiterhin und ist für komplexe, gesten-getriebene Animationen weiterhin der richtige Weg.

Voraussetzungen und Installation

Bevor Sie installieren, prüfen Sie drei Dinge: Ihre React-Native-Version (mindestens 0.78), den Status der New Architecture in Ihrer App und die Expo-SDK-Version (mindestens 54 für Expo-Projekte). Reanimated 4 läuft nicht auf React Native 0.74 oder älter und auch nicht auf Apps, in denen Fabric in app.json oder gradle.properties noch deaktiviert ist.

Die Installation hat sich gegenüber v3 leicht geändert, weil Worklets jetzt ein eigenes Paket sind:

npx expo install react-native-reanimated react-native-worklets
# oder im Bare-Workflow:
yarn add react-native-reanimated react-native-worklets
cd ios && pod install

Anschließend müssen Sie das Worklets-Plugin in Ihrer babel.config.js registrieren, und zwar als letztes Plugin, sonst greift die Transformation nicht:

// babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: ['react-native-worklets/plugin'], // immer letzter Eintrag
  };
};

Die neue CSS-Animations-API

Die CSS-Animations-API von Reanimated 4 lehnt sich bewusst an das Web an. Sie kennen transition und animation-Properties aus CSS, und genau diese Bezeichner stehen jetzt auf dem Style-Objekt zur Verfügung. Ein einfacher Übergang sieht so aus:

import Animated from 'react-native-reanimated';
import { useState } from 'react';
import { Pressable, Text } from 'react-native';

export function FadeButton() {
  const [active, setActive] = useState(false);

  return (
    <Pressable onPress={() => setActive(!active)}>
      <Animated.View
        style={{
          width: 200,
          height: 60,
          backgroundColor: active ? '#3b82f6' : '#e5e7eb',
          opacity: active ? 1 : 0.6,
          transitionProperty: ['backgroundColor', 'opacity'],
          transitionDuration: 220,
          transitionTimingFunction: 'ease-out',
        }}
      >
        <Text>Tippen</Text>
      </Animated.View>
    </Pressable>
  );
}

Kein useSharedValue, kein useAnimatedStyle, keine Worklet-Direktive. Reanimated registriert die genannten Properties als animierbar und interpoliert beim nächsten Render-Pass im UI-Thread. Für Keyframes gibt es die Schwester-API animationName:

import Animated from 'react-native-reanimated';

const bounce = {
  '0%': { transform: [{ translateY: 0 }] },
  '50%': { transform: [{ translateY: -24 }] },
  '100%': { transform: [{ translateY: 0 }] },
};

export function BouncingDot() {
  return (
    <Animated.View
      style={{
        width: 16,
        height: 16,
        borderRadius: 8,
        backgroundColor: '#10b981',
        animationName: bounce,
        animationDuration: 800,
        animationIterationCount: 'infinite',
      }}
    />
  );
}

In meinen Messungen läuft diese deklarative Variante exakt so schnell wie die äquivalente useAnimatedStyle-Implementierung — beide werden auf demselben UI-Thread-Compiler übersetzt. Der Gewinn ist also nicht Performance, sondern Lesbarkeit und weniger Boilerplate für die 80 % der Fälle, die keine Geste brauchen.

Das neue Worklets-Paket

Mit v4 wandert die Worklets-Runtime aus Reanimated heraus in react-native-worklets. Der Hintergrund: Andere Bibliotheken wie React Native Skia und Vision Camera nutzen dieselbe Runtime, und ein einzelnes Paket vermeidet doppelte Installation und Versionskonflikte. Für Sie als App-Entwickler ändert sich an der 'worklet'-Direktive nichts:

import { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
import { Gesture, GestureDetector } from 'react-native-gesture-handler';

export function DraggableBox() {
  const x = useSharedValue(0);
  const y = useSharedValue(0);

  const pan = Gesture.Pan()
    .onChange((event) => {
      'worklet';
      x.value += event.changeX;
      y.value += event.changeY;
    })
    .onEnd(() => {
      'worklet';
      x.value = withSpring(0);
      y.value = withSpring(0);
    });

  const style = useAnimatedStyle(() => ({
    transform: [{ translateX: x.value }, { translateY: y.value }],
  }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[{ width: 80, height: 80, backgroundColor: '#f97316' }, style]} />
    </GestureDetector>
  );
}

Dieses imperative Muster bleibt der richtige Weg für alles, was auf Eingaben reagiert (Gesten, Scroll-Listener, Audio-Pegel). Die CSS-API kann auf solche Live-Werte nicht reagieren, weil sie Render-getrieben ist und nicht Worklet-getrieben.

Migration von Reanimated 3 auf v4

Mein Migrationspfad in beiden Apps lief in vier Schritten ab. Erstens: Sicherstellen, dass Fabric überall aktiv ist. Zweitens: Reanimated und Worklets gemeinsam installieren. Drittens: Babel-Plugin austauschen. Viertens: Ein typischer Codebase-Scan nach Deprecations.

New Architecture aktivieren in app.json über "newArchEnabled": true und in iOS via RCT_NEW_ARCH_ENABLED=1 pod install.
Pakete aktualisieren: npx expo install react-native-reanimated@~4.0.0 react-native-worklets.
Babel-Plugin tauschen: react-native-reanimated/plugin wird zu react-native-worklets/plugin.
Codebase-Scan: Die Funktion useAnimatedGestureHandler ist endgültig entfernt; sie war seit v3 deprecated. Ersetzen Sie sie durch die Gesture-API aus react-native-gesture-handler 2.21+.

Für die Kompatibilität mit anderen Libraries: Expo Router v5 ist Reanimated-4-kompatibel ab Patch 5.0.3. FlashList v2 unterstützt v4 nativ und nutzt es intern für Item-Animationen. Wenn Sie Zustand-Selectors mit animierten Werten kombinieren, lesen Sie meinen Zustand-State-Management-Leitfaden — die Empfehlung, Animation-State außerhalb des Stores zu halten, gilt in v4 unverändert.

Wie funktionieren Shared Element Transitions in Reanimated 4?

Shared Element Transitions sind eine der sichtbarsten Neuerungen, weil sie endlich stabil sind. In v3 waren sie experimentell und scheiterten oft an Layout-Race-Conditions zwischen Native- und JS-Thread. In v4 mit Fabric läuft der Transition-Berechnungs-Schritt synchron im UI-Thread, was die typischen "Element springt kurz an die falsche Stelle"-Bugs eliminiert.

// auf der Listen-Seite:
import Animated from 'react-native-reanimated';

<Animated.Image
  source={{ uri: item.image }}
  sharedTransitionTag={`photo-${item.id}`}
  style={{ width: 120, height: 120 }}
/>

// auf der Detail-Seite (gleiches Tag):
<Animated.Image
  source={{ uri: item.image }}
  sharedTransitionTag={`photo-${item.id}`}
  style={{ width: '100%', height: 320 }}
/>

Das funktioniert mit Expo Router v5 und React Navigation 7 out of the box. Wichtig ist, dass das Tag eindeutig pro Frame ist. Wenn dasselbe Tag in mehr als zwei Komponenten gleichzeitig montiert ist, friert die Transition ein. Ich validiere das in größeren Apps mit einem kleinen Debug-Hook, der bei Mount alle Tags in einem Set zählt und in DEV warnt.

Performance im Vergleich zu Reanimated 3

Ich habe denselben Screen (eine Liste mit 200 animierten Karten) in beiden Versionen profiliert. Gemessen auf einem iPhone 13 und einem Pixel 7, Release-Build, Hermes aktiv:

Metrik	Reanimated 3.16	Reanimated 4.0
Durchschnittliche Frame-Zeit	11.8 ms	10.4 ms
JS-Thread-Last während Scroll	14 %	9 %
UI-Thread-Last während Scroll	22 %	21 %
Bundle-Size-Delta (iOS, gzipped)	0 KB Baseline	+31 KB
Kaltstart-Zeit (Pixel 7)	912 ms	880 ms
Shared-Transition-Glitches pro 100 Wechseln	4	0

Die JS-Thread-Entlastung kommt vor allem aus der CSS-API, weil viele kleine useAnimatedStyle-Aufrufe wegfallen. Der Bundle-Size-Overhead ist real, aber moderat; bei den Apps, die ich migriert habe, ging der Cold-Start trotzdem leicht runter, weil die TurboModule-Registrierung schneller läuft als das alte Bridge-Init.

Wann sollte ich die CSS-API statt useAnimatedStyle verwenden?

Meine Faustregel nach mehreren Monaten Produktivnutzung: Verwenden Sie die CSS-API immer dann, wenn der Endzustand der Animation bereits zur Render-Zeit bekannt ist. Beispiele: ein Button, der zwischen aktiv und inaktiv wechselt; eine Karte, die bei isExpanded ihre Höhe verändert; ein Skeleton-Loader, der zwischen zwei Farben pulsiert. In all diesen Fällen kennen Sie beide Zustände vorab, und die deklarative API ist deutlich kürzer und weniger fehleranfällig.

Greifen Sie zur klassischen Worklet-API, sobald sich der Zielwert kontinuierlich aus einem Input ableitet, also bei Drag-Gesten, Scroll-Position-Tracking, Pinch-to-Zoom oder Audio-Visualisierern. Auch komplexe orchestrierte Sequenzen, bei denen eine Animation auf den Abschluss einer anderen wartet, sind in der imperativen API mit withSequence sauberer auszudrücken als in CSS-Keyframes. Eine Mischform funktioniert ohne Performance-Strafe: ein Drag-Wrapper im Worklet-Modus, dessen Kind-Komponenten die CSS-API für Sekundäranimationen nutzen.

Footguns und häufige Fehler

Drei Stolpersteine, die mich Zeit gekostet haben und die in der Doku eher beiläufig stehen.

Doppelt registriertes Babel-Plugin

Wenn nach der Installation alle Animationen plötzlich nicht mehr starten und Sie im Log "Worklet not registered" sehen, ist meistens das alte react-native-reanimated/plugin noch in der babel-config. Beide Plugins gleichzeitig zerlegen den Transform-Pass. Ein npx expo prebuild --clean und ein Cache-Reset (npx expo start -c) sind danach Pflicht.

CSS-Properties auf Nicht-Animated-Komponenten

Die neuen Properties (transitionProperty, animationName etc.) funktionieren nur auf Animated.View, Animated.Image und Animated.ScrollView. Wenn Sie sie auf ein normales View setzen, werden sie stillschweigend ignoriert. Kein Fehler, einfach keine Animation. Das ist der häufigste Bug-Report aus meinem Team.

Inkompatible Gesture-Handler-Version

Reanimated 4 benötigt react-native-gesture-handler 2.21 oder neuer. Ältere Versionen kompilieren, werfen aber zur Laufzeit beim ersten Gesten-Event einen Fehler, weil sich die Worklet-Runtime-Schnittstelle leicht geändert hat. Die Release Notes auf GitHub nennen die exakten Minimumversionen für die wichtigsten Companion-Libraries.

Häufig gestellte Fragen

Brauche ich für Reanimated 4 zwingend die New Architecture?

Ja. Reanimated 4 läuft ausschließlich auf Fabric und TurboModules. Apps, die noch auf der alten Bridge laufen, müssen entweder zuerst auf die New Architecture migrieren oder auf Reanimated 3 bleiben. Einen Kompatibilitätsmodus gibt es nicht.

Kann ich die CSS-Animations-API mit useSharedValue mischen?

Ja. Beide APIs koexistieren auf derselben Animated-Komponente. Statische Übergänge (Hover, Aktivierung) gehören in die CSS-API, gesten- oder scroll-gebundene Animationen in das klassische Shared-Value-Modell.

Funktioniert Reanimated 4 mit Expo Go?

Eingeschränkt. Expo Go bündelt eine feste Reanimated-Version pro SDK. Für SDK 54+ ist v4 enthalten; für ältere SDKs müssen Sie auf einen Development Build umsteigen, weil das Worklets-Plugin nativen Code benötigt.

Was passiert mit useAnimatedGestureHandler?

Die Funktion ist in v4 entfernt. Verwenden Sie stattdessen die Gesture-Builder-API aus react-native-gesture-handler (Gesture.Pan(), Gesture.Tap() etc.) zusammen mit GestureDetector.

Wie performant ist die neue CSS-API im Vergleich zur Web-Variante?

Auf demselben Niveau. Reanimated kompiliert die CSS-Properties in UI-Thread-Worklets, die wie Web-CSS-Transitions GPU-beschleunigt laufen. In meinen Messungen erreicht ein typischer Übergang konstant 60fps auf Mittelklasse-Geräten und 120fps auf ProMotion-iPhones.