Animaatiot ja UI 11 min lukuaikaIntermediate

React Native Reanimated 4 (2026): Worklets, CSS-animaatiot ja migraatio versiosta 3

Reanimated 4 vaatii uuden arkkitehtuurin ja tuo deklaratiivisen CSS-animaatio-API:n. Käymme läpi asennuksen Expo SDK 54-55:lle, ydinkäsitteet (worklet, sharedValue), Gesture Handler 2 -integraation sekä migraation 3 → 4 toimivin koodiesimerkein.

Jake Morrison
Reanimated 4 Opas: Worklets & CSS (2026)

Päivitetty: 30. toukokuuta 2026

React Native Reanimated 4 on Software Mansionin ylläpitämä animaatiokirjasto, joka ajaa animaatiot UI-säikeellä worklettien kautta ja tarjoaa nyt myös deklaratiivisen, CSS-yhteensopivan API:n. Reanimated 4 vaatii uuden arkkitehtuurin (Fabric), tukee kolmea uusinta React Native -versiota ja korvaa pitkälti vanhan Animated-API:n tuotantokäytössä. Tässä oppaassa käydään läpi asennus Expo SDK 54–55:llä, keskeiset hookit, CSS-animaatiot, yleisimmät karikot sekä 3 → 4 -migraatio käytännön esimerkein.

  • Reanimated 4.4 (toukokuu 2026) vaatii New Architecturen. Vanha Paper-renderöijä ei toimi.
  • Babel-plugin siirtyi: käytä react-native-worklets/plugin aiemman react-native-reanimated/plugin sijaan, ellet käytä babel-preset-expoa.
  • Uusi CSS-API (animationName, transitionProperty) korvaa noin 80 % yksinkertaisista worklet-pohjaisista animaatioista.
  • Expo SDK 54 → Reanimated 4.1.x; Expo SDK 55 vaatii pelkän New Archin, eikä sitä voi enää poistaa käytöstä.
  • Hookit useSharedValue, useAnimatedStyle ja withSpring/withTiming ovat edelleen ydintä; useAnimatedGestureHandler on poistettu.
  • Reanimated voittaa Animated-API:n suorituskyvyssä useimmissa tuotantotapauksissa, koska se ei kuormita JS-säiettä.

Mikä on React Native Reanimated 4?

Reanimated on Software Mansionin kehittämä animaatiokirjasto, joka suorittaa animaatiot natiivin UI-säikeen päällä eikä JavaScript-säikeellä, kuten React Nativen sisäänrakennettu Animated-moduuli. Käytännössä tämä tarkoittaa, että edes raskas JS-puolen työ (listojen renderöinti, GraphQL-pyynnöt, kuvaprosessointi) ei aiheuta animaatioihin nykimistä. Reanimated 4:n vakaa julkaisu tuli ulos kesällä 2025, ja toukokuun 2026 vakaaversio on 4.4.

Tärkein konseptuaalinen muutos versioon 3 verrattuna on kaksi rinnakkaista API-tasoa. Imperatiivinen worklet-pohjainen API (useSharedValue, useAnimatedStyle) säilyy ennallaan, ja sen rinnalla tulee uusi deklaratiivinen CSS-yhteensopiva API. Jos olet rakentanut webillä CSS-keyframea, uusi API tuntuu välittömästi tutulta, ja voit määritellä animationName, animationDuration ja animationIterationCount suoraan tyyleinä. Olen päivittänyt kolmesta tuotantoprojektista kaksi versioon 4 viimeisten kuuden kuukauden aikana, ja molemmissa noin 80 % yksinkertaisista worklet-animaatioista kaatui yhden CSS-rivin alle.

Reanimated 4 on rakennettu olettamuksena, että käytät Fabricia. Vanhan arkkitehtuurin (Paper) tuki on poistettu. Jos projektisi on edelleen Paperin päällä, joudut joko jäämään Reanimated 3.x:ään tai migroimaan ensin uuteen arkkitehtuuriin. Lue lisää oppaasta Expo SDK ja React Nativen uusi arkkitehtuuri, jossa käyn migraation läpi vaiheittain.

Reanimated 4:n asennus Expo SDK 54–55 -projektiin

Expo-projektissa asennus on yhden komennon työ, koska babel-preset-expo rekisteröi worklets-pluginin automaattisesti. Pelkässä React Native CLI -projektissa joudut konfiguroimaan Babelin itse. Asennan itse aina paketin Expon CLI:n kautta, jotta SDK-versiollesi pinnoittuu yhteensopiva versio. Älä asenna pakettia suoraan npm install -komennolla, sillä silloin saatat saada liian uuden version, joka kaatuu builtissa.

npx expo install react-native-reanimated

Expo SDK 54:lle pinnoittuu Reanimated 4.1.x, ja Expo SDK 55:lle 4.4.x. Pelkkä React Native (versiot 0.78–0.82):

npm install react-native-reanimated react-native-worklets
# tai
yarn add react-native-reanimated react-native-worklets

Lisää Babel-plugin babel.config.js-tiedostoon viimeiseksi pluginiksi:

module.exports = {
  presets: ['module:@react-native/babel-preset'],
  plugins: [
    // Muut pluginit ensin
    'react-native-worklets/plugin', // TÄMÄN ON OLTAVA VIIMEINEN
  ],
};

Lopuksi tyhjennä Metron välimuisti ja käynnistä bundler uudestaan:

npx expo start --clear
# tai
npx react-native start --reset-cache

Tarkista vielä, että uusi arkkitehtuuri on päällä. Expo SDK 54:ssä app.json:

{
  "expo": {
    "newArchEnabled": true
  }
}

Expo SDK 55:ssä lippu on poistettu, sillä uusi arkkitehtuuri on aina päällä, eikä sitä voi enää kytkeä pois.

Ydinkäsitteet: worklet, sharedValue ja UI-säie

Reanimatedin ymmärtämiseksi pitää tietää kolme käsitettä: worklet, jaettu arvo ja säikeiden välinen viestintä. Worklet on JavaScript-funktio, joka ajetaan natiivilla UI-säikeellä eikä JS-säikeellä. Kääntäjä siirtää workletin runtime-kontekstiin asennuksen yhteydessä. Worklet-funktion sisältä et voi viitata mihin tahansa JS-muuttujaan, vain serialisoitaviin arvoihin ja muihin workletteihin.

Shared value (useSharedValue) on muistipala, jota molemmat säikeet voivat lukea ja kirjoittaa atomisesti. Tyypillinen käyttö on tallentaa siihen animoitava numero, kuten X-translaatio tai opasiteetti. Kun shared value muuttuu workletin sisällä, Reanimated osaa renderöidä uuden tyylin ilman setStatea, kontekstinvaihtoa tai sillan ylittävää viestiä.

Säikeiden välistä viestintää varten on kaksi funktiota: runOnJS kutsuu JS-puolen funktion (esim. navigaation tai analytiikan) UI-säikeeltä, ja runOnUI ajaa workletin UI-säikeellä JS-puolen koodista käsin. Versio 4 lisäsi vielä runOnUISync-kutsun, joka odottaa workletin valmistumista. Käytä sitä varovasti, koska se voi blokata renderöinnin.

Reanimated 4:n virallinen termistö Software Mansionin dokumentaatiossa on lyhyt ja kannattaa lukea läpi kerran, sillä säästyt monilta väärinkäsityksiltä myöhemmin.

Käytännön esimerkit: useSharedValue ja useAnimatedStyle

Klassinen esimerkki on painalluksesta laajeneva korttinäkymä. Tässä toteutus, joka skaalaa ja muuttaa opasiteettia jousiliikkeellä:

import React from 'react';
import { Pressable, Text } from 'react-native';
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
} from 'react-native-reanimated';

export function PressableCard({ children }) {
  const scale = useSharedValue(1);
  const opacity = useSharedValue(1);

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ scale: scale.value }],
    opacity: opacity.value,
  }));

  const handlePressIn = () => {
    scale.value = withSpring(0.96, { damping: 12, stiffness: 180 });
    opacity.value = withSpring(0.85);
  };

  const handlePressOut = () => {
    scale.value = withSpring(1);
    opacity.value = withSpring(1);
  };

  return (
    <Pressable onPressIn={handlePressIn} onPressOut={handlePressOut}>
      <Animated.View style={[styles.card, animatedStyle]}>
        <Text>{children}</Text>
      </Animated.View>
    </Pressable>
  );
}

Huomaa kolme asiaa. Ensinnäkin useAnimatedStyle-callback on worklet, joten voit lukea scale.valuen suoraan, mutta et voi viitata vapaisiin JS-muuttujiin (kuten props.something). Toiseksi withSpring ottaa konfiguraatio-olion, jossa versio 4 yhdisti vanhat restDisplacementThreshold ja restSpeedThreshold yhdeksi energyThresholdiksi. Kolmanneksi animaatio ei aiheuta yhtään uudelleenrenderöintiä React-puolella, sillä koko muutos tapahtuu UI-säikeellä.

Jos haluat ajaa funktion JS-puolella animaation valmistuttua, käytä withSpring-callbackia ja runOnJS:ää:

const handlePress = () => {
  scale.value = withSpring(1.2, {}, (finished) => {
    if (finished) {
      runOnJS(navigation.navigate)('Detail');
    }
  });
};

Uusi CSS-animaatio-API käytännössä

Reanimated 4:n näkyvin uutuus on deklaratiivinen tyylipohjainen API. Voit määritellä animaation kuten CSS:ssä, ilman shared valueita tai workletteja:

import Animated from 'react-native-reanimated';

const styles = {
  pulse: {
    width: 80,
    height: 80,
    borderRadius: 40,
    backgroundColor: '#4f46e5',
    animationName: {
      from: { transform: [{ scale: 1 }] },
      to:   { transform: [{ scale: 1.2 }] },
    },
    animationDuration: '600ms',
    animationIterationCount: 'infinite',
    animationDirection: 'alternate',
    animationTimingFunction: 'ease-in-out',
  },
};

export const Pulse = () => <Animated.View style={styles.pulse} />;

Sama logiikka olisi vienyt vanhalla API:lla noin 25 riviä: useSharedValue, useEffect ja withRepeat(withTiming(...), -1, true). Lyhyydellä on hintansa: monimutkaisemmat orkestroinnit, kuten useamman arvon yhdistäminen tai gestureen kytkeminen, vaativat edelleen workletteja. Käytännön nyrkkisääntö, jota itse seuraan: yksinkertaiset toistuvat animaatiot ja transitio-efektit CSS:llä, kaikki interaktiivinen workletteina.

Transitio-API toimii erikseen. Voit määrittää, että tietyt tyyliominaisuudet animoituvat aina, kun niiden arvo muuttuu:

const cardStyle = {
  backgroundColor: isActive ? '#4f46e5' : '#e5e7eb',
  transitionProperty: ['backgroundColor', 'transform'],
  transitionDuration: '200ms',
};

Layout-animaatiot ja entering/exiting-siirtymät

Layout-animaatiot animoivat komponentin saapumisen, poistumisen ja layout-muutokset ilman, että sinun tarvitsee laskea positiota itse. Tämä on hyödyllistä esimerkiksi listan elementtien poistumisanimaatiossa tai uuden viestin liu'utuksessa keskusteluikkunaan.

import Animated, {
  FadeOut,
  SlideInRight,
  LinearTransition,
} from 'react-native-reanimated';

function MessageList({ messages }) {
  return (
    <Animated.FlatList
      data={messages}
      itemLayoutAnimation={LinearTransition}
      renderItem={({ item }) => (
        <Animated.View
          entering={SlideInRight.duration(250)}
          exiting={FadeOut.duration(150)}
        >
          <MessageBubble {...item} />
        </Animated.View>
      )}
    />
  );
}

Yhdistettynä FlashListin suorituskykyetuihin tämä on rakentava yhdistelmä keskusteluikkunoille ja syötteille, sillä saat sekä sileän skrollin että pehmeät siirtymät. Layout-animaatiot ajetaan UI-säikeellä, joten ne eivät kärsi vaikka JS-puolella ladattaisiin uutta dataa samaan aikaan. Olen huomannut, että LinearTransition on yleensä riittävä; jos siirtymässä pitäisi olla jousiluonne, käytä LinearTransition.springify().damping(14).

Gesture Handler 2 -integraatio

Versiossa 4 poistui useAnimatedGestureHandler. Eleitä käsitellään nyt suoraan Gesture Handler 2:n uudella Gesture-API:lla, ja shared valuet liitetään animaatioon samalla tavalla kuin aiemmin.

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

function DraggableSquare() {
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);

  const pan = Gesture.Pan()
    .onChange((event) => {
      translateX.value += event.changeX;
      translateY.value += event.changeY;
    })
    .onEnd(() => {
      translateX.value = withSpring(0);
      translateY.value = withSpring(0);
    });

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

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[styles.square, style]} />
    </GestureDetector>
  );
}

Tämä on koko gesture-integraation pohja: ei Animated.eventiä, ei sillan ylittävää viestintää, vain shared valueiden suora mutaatio worklet-callbackin sisällä. Vakavammin animoiduissa komponenteissa (bottom sheet, drawer) kannattaa katsoa myös react-native-gesture-handlerin dokumentaatiosta uudet Gesture.Simultaneous ja Gesture.Exclusive -komposiittorakenteet, jotka ratkovat eleiden välisen prioriteetin ilman manuaalista state-jonglöörausta.

Migraatio Reanimated 3:sta 4:een

Migraatio kolmosesta neloseen on suoraviivainen, jos olet jo uudella arkkitehtuurilla. Käytännössä menen seuraavassa järjestyksessä:

  1. Päivitä paketti: npx expo install react-native-reanimated tai npm i react-native-reanimated@latest react-native-worklets.
  2. Vaihda Babel-plugin react-native-reanimated/plugin → react-native-worklets/plugin (paitsi Expo, joka hoitaa tämän).
  3. Korvaa useAnimatedGestureHandler uudella Gesture-API:lla. Olen huomannut, että muunnos vie keskimäärin 20–30 minuuttia per gesture-komponentti.
  4. Etsi executeOnUIRuntimeSync ja vaihda nimeen runOnUISync.
  5. Päivitä withSpring-konfiguraatiot: yhdistä restDisplacementThreshold ja restSpeedThreshold uudeksi energyThresholdiksi.
  6. Poista addWhitelistedNativeProps ja addWhitelistedUIProps -kutsut, sillä ne ovat no-op-funktioita ja vain sotkevat koodia.
  7. Tyhjennä välimuisti ja aja sovellus läpi. Useimmat virheet näkyvät heti käynnistyksessä, eivät vasta tuotannossa.

Virallinen Software Mansionin migraatio-opas sisältää täydellisen listan rikkovista muutoksista. Käy se läpi ennen kuin painat git commit, niin vältät pari ikävää yllätystä.

Reanimated vs Animated API vs Moti

Yleisin kysymys uusilta tiimiläisiltä on, milloin kannattaa käyttää mitäkin animaatiokirjastoa. Lyhyt vastaukseni: uudessa projektissa Reanimated 4, koska se yhdistää suorituskyvyn ja deklaratiivisen API:n. Mutta perustelut on hyvä tuntea.

OminaisuusReanimated 4Animated APIMoti
SäieUI-säie (worklets)JS-säie + native driverUI-säie (Reanimatedin päällä)
API-tyyliImperatiivinen + CSSImperatiivinenDeklaratiivinen (Framer Motion -tyyli)
OppimiskäyräKohtalainenMatala alkuun, monimutkainen myöhemminMatala
Layout-animaatiotSisäänrakennettuEi tuettuReanimatedin kautta
Gesture-integraatioErinomainenHeikkoHyvä
Pakettikoko~250 KBSisäänrakennettu~30 KB lisäys
TuotantokäyttöVakiintunutVakiintunut, mutta rajoittunutSuositeltu prototyypeille

Käytännössä Animated-API:n nykimisongelma näkyy heti, kun JS-säie kuormittuu. Jos sovelluksesi animoi vain modaaleja ja toast-viestejä, ero ei välttämättä näy. Mutta heti kun käyttäjä skrollaa pitkää listaa samalla, kun bottom sheet liukuu auki, Reanimated voittaa selvästi. Moti puolestaan kannattaa, jos haluat kirjoittaa todella vähän koodia ja suorituskyky ei ole pullonkaula; se käyttää Reanimatedia moottorina, joten saat saman UI-säikeen edut.

Yleiset virheet ja niiden korjaaminen

Listaan tähän viisi yleisintä virhettä, joihin tiimi törmää Reanimated 4:n käytössä, ja jokaiseen suoran ratkaisun.

1. "Reanimated 2 failed to create a worklet". Babel-plugin puuttuu tai ei ole viimeisenä. Lisää react-native-worklets/plugin listan loppuun, tyhjennä Metron välimuisti.

2. "Tried to synchronously call function from a different thread". Yrität kutsua tavallista JS-funktiota worklet-kontekstista. Kääri kutsu runOnJS(myFunction)(args):lla.

3. Animaatio ei käynnisty. Tarkista, että käytät Animated.Viewiä etkä tavallista Viewiä. Yleinen virhe, kun komponentti on importattu väärin.

4. "Cannot find module 'react-native-worklets'". Reanimated 4:ssä worklets on oma paketti. Asenna se erikseen, jos et käytä Expoa.

5. Animaatio nytkähtää debug-buildissa, mutta toimii release-buildissa. Debuggerin kytkeminen pakottaa worklets-suorituksen JS-säikeelle. Käytä React Native DevToolsia Hermes-debuggerin sijaan.

Usein kysytyt kysymykset

Mikä on Reanimated 3:n ja 4:n suurin ero?

Reanimated 4 vaatii uuden arkkitehtuurin, tuo deklaratiivisen CSS-animaatio-API:n ja siirtää worklets-toteutuksen omaan pakettiinsa. Vanha imperatiivinen API (useSharedValue, useAnimatedStyle) toimii edelleen melkein muuttumattomana, mutta useAnimatedGestureHandler on poistettu.

Toimiiko Reanimated 4 vanhalla arkkitehtuurilla (Paper)?

Ei. Reanimated 4 vaatii Fabricin. Jos olet vielä Paperilla, joko jää Reanimated 3.x:ään tai migroi uuteen arkkitehtuuriin ensin. Expo SDK 55 lopettaa Paperin tuen kokonaan.

Miksi saan virheen "react-native-reanimated/plugin was moved"?

Versiossa 4 Babel-plugin siirtyi pakettiin react-native-worklets. Vaihda babel.config.js:ssä polku react-native-reanimated/plugin → react-native-worklets/plugin ja tyhjennä Metron välimuisti komennolla npx expo start --clear.

Mikä on worklet ja miksi sitä tarvitaan?

Worklet on JavaScript-funktio, jonka Reanimatedin kääntäjä siirtää suoritettavaksi natiivilla UI-säikeellä. Worklet voi lukea ja kirjoittaa shared valueita ilman sillan ylittämistä, mikä tekee animaatioista tasaisia myös JS-säikeen ollessa kuormitettu.

Kannattaako Reanimated vai Moti uudessa projektissa?

Pienissä projekteissa ja prototyypeissä Moti antaa nopeimman tuottavuuden, koska sen Framer Motion -tyyppinen API on suoraviivainen. Vakavammassa tuotantoprojektissa suosittelen Reanimated 4:ää suoraan. Moti käyttää sitä silti pinnan alla, ja saat enemmän hallintaa monimutkaisiin gesture- ja layout-animaatioihin.

Miten yhdistän Reanimated 4:n ja React Navigationin sivunvaihdoissa?

React Navigation 7 käyttää sisäisesti Reanimatedia siirtymiin, joten ne ovat automaattisesti yhteensopivia. Voit luoda omia siirtymiä screenAnimation-vaihtoehdolla ja shared valueilla, jotka liittyvät navigaation tilaan useAnimatedReactionin kautta.

Jake Morrison
Tietoa Kirjoittajasta Jake Morrison

React Native lead engineer who's shipped six apps and learned six different lessons. Bullish on the New Architecture.