A while ago, we shared the beta version of the next major release of Reanimated. After six months of work today, we are publishing the first stable version of Reanimated 4.

As promised, this is the biggest and most important release since we introduced the concept of worklets in Reanimated 2, and proposed our novel, UI-thread-based animations engine on top of it. Worklets have become a very important part of the React Native ecosystem and have inspired a lot of other projects to build on these foundations. This major release takes the worklets to the next level, while also bringing a new, declarative, CSS-compatible animation API that aims to replace worklets in many of the use cases. Watch our short announcement video to get a high-level overview of what this release is all about.

Start using CSS animations and transitions

CSS-based animations and transitions API is the key highlight of this release. For a while now, we’ve been thinking of providing a clear, declarative API for the most frequent type of animations that are triggered and controlled by state updates (rather than gestures, scroll position, etc). Declarative animations would simplify many parts of your codebase as before, even a simple animation would require a shared value and an animated style worklet. We eventually settled on CSS animations and transitions, as it is a well-known, battle-tested, and complete standard. We not only hope that it will make Reanimated more accessible for developers coming from the web, but also let React Native developers learn or stay familiar with these APIs.

Another benefit of the CSS declarative animations in Reanimated is that they are much easier to optimize. This comes from the fact that we understand many more details about what attributes of which components are being animated this way. With shared values, the information that we otherwise get here explicitly would’ve needed to be computed based on relations between shared or derived values. We therefore recommend the state-controlled animations to start adopting the CSS API from Reanimated. You should expect it to yield less code (no hook calls), and also to perform better (with more optimizations coming in future updates). If in doubt, check out our example app for a showcase of the power of this API:

But what about the worklets?

Using worklets and shared values is still the recommended approach when it comes to more complex scenarios. For example, gesture or scroll-driven animations, screen transition animations, or scenarios where multiple derived animations need to be orchestrated. Please, don’t feel like you should rewrite all your code to CSS animations right now — we also have a number of performance-related improvements for Worklets up our sleeves.

Worklets are getting more care than ever before. The code has been moved to a separate package react-native-worklets, to help us accelerate the progress independently and to also open it up for other non-animation packages to utilize. In fact, the move already happened in the 3.17 version and no one even noticed. From the Reanimated user perspective, this change is completely transparent as Worklets are just an internal dependency of Reanimated. The installation guide in Reanimated 4 now requires listing react-native-worklets/plugin instead of react-native-reanimated/plugin in your Babel configuration. If you have an existing app, you can make this change, but the old version will continue to work for the foreseeable future.

Breaking changes

Reanimated 4 API is compatible with Reanimated 3, and you should expect to make no code changes when updating (terms and conditions apply™). Our library is used by tens of thousands of apps and libraries from the ecosystem. Therefore, we put extra care into making the process of adapting new versions by the community as easy as it can be. Reanimated 4 requires that your app uses the React Native New Architecture, migrating to which may already require some work and effort. Once your app uses the New Architecture, you can upgrade to Reanimated 4 with little to no required changes and start adapting new features like CSS animations incrementally.

To keep improving Reanimated, we sometimes have to let go of some bad design decisions, but whenever we do it, we try to minimize the impact to users and be very clear about those changes. This time again, we will be dropping some of the rarely used methods that were already deprecated in Reanimated 3. A few, now obsolete methods will be getting deprecation notices but continue to function as no-op for backward compatibility. If you want the details, please consult our full migration guide here.

On top of the API-level alterations, there is also one behavior-related change to the spring animation — in Reanimated 4, it uses a new default setting. If you had a custom setting for your spring animation, those will still be honored. For all the other cases, the change should be subtle, and in our opinion, provide better, more natural behavior. Our original spring implementation was meant to mimic the one from React Native core. Over time, we discovered this method was somewhat cumbersome. The spring mechanics proved overly sensitive to start and end conditions, frequently leading to erratic or completely incorrect behavior unless obscure threshold parameters were adjusted correctly. The new spring implementation works well without the need to specify these threshold parameters (you can still provide them, though, for backwards compatibility). When using springs, we recommend specifying just the duration and damping ratio. This leads to more predictable behavior for the user, as the animation will finish at the given time regardless of the distance. See the new spring in action:

Final notes

It’s been five years since we started collaborating with Shopify to revamp the animation space in React Native with Reanimated 2. We’re thankful for their trust and support throughout this journey! We also wanted to thank the React Native core team at Meta for their dedication and support in resolving issues at the intersection of Reanimated and React Native.

Reanimated 4 is new, but at the same time also very familiar. We believe that with all the additions it will bring your app to the next level and empower even more developers to create stunning, animation-rich mobile app interfaces that users will adore.

A few useful links:

• Check out the full release notes on GitHub
• Read more about CSS Transitions
• Read more about CSS Animations

We’re Software Mansion: multimedia experts, AI explorers, React Native core contributors, community builders, and software development consultants. If you need help with your product, drop us an email at [email protected], or fill in our contact form.