Skip to content
Get packs

Guide · Open source

How to use react-native-reanimated: setup, basics and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

React Native Reanimated is an MIT-licensed library for building animations and interactions in React Native mobile apps, and it is written in TypeScript. It is aimed at React Native developers who are building animated or gesture-heavy screens. This guide explains what the library and its companion, React Native Worklets, do, what you need before installing, where to find the official setup steps, and how to avoid common pitfalls.

Reanimatedsoftware-mansion/react-native-reanimated · ★ 11k · MIT

Quick start

  1. 1Confirm your project fits. Check that you have a React Native project using the New React Native architecture. If you are on the old architecture, plan to use the latest 3.x release.
  2. 2Read the official install guides. Open the getting-started pages for Reanimated and Worklets in the official docs and follow the installation steps there.
  3. 3Install both packages. Add Reanimated and Worklets to your project as the documentation describes.
  4. 4Try the example app. Clone the repository if you want to explore the showcase app in apps/common-app before adding animations to your own screens.
  5. 5Build a small animated screen. Start with one simple animation in a non-critical screen to confirm your setup works.
  6. 6Consult the API reference. Use the Reanimated API reference whenever you need details on a specific feature.

What is react-native-reanimated and what does it do?

React Native Reanimated is a library for creating smooth animations and interactions in React Native. The repository that hosts it also contains React Native Worklets, a separate library that enables multi-threaded JavaScript execution in React Native applications.

According to the project's analysis, developers use these libraries so that animations keep running smoothly while the app is busy.

Check the prerequisites before you install

Reanimated 4.x and Worklets support only the New React Native architecture and the three latest React Native versions. The project's compatibility notes recommend adopting the New Architecture, or staying on the latest 3.x release if your app still runs on the old architecture.

The README also assumes familiarity with React Native, so this library is a poor first step for someone with no React Native experience.

  • Your project must be a React Native project.
  • It must use the New React Native architecture to use Reanimated 4.x.
  • If you are on the old architecture, use the latest 3.x release instead.

Install Reanimated and Worklets

The README points to the official documentation for installation instructions for both Reanimated and Worklets rather than listing package commands itself. Follow those pages for the exact steps for your setup.

The only command given in the README is for cloning the repository, which is useful if you want to read the source or run the example project.

  • Reanimated installation: see the getting-started page in the Reanimated documentation.
  • Worklets installation: see the getting-started page in the Worklets documentation.
git clone https://github.com/software-mansion/react-native-reanimated.git

Explore the example app before writing your own code

The source code for the example (showcase) app lives in the apps/common-app directory of the repository. If you want to try the API without touching a real app, the README says you can run the example project and points to an example README for its installation instructions.

Reading the showcase is a practical way to see how animated screens are structured before you build your own.

  • Source of the showcase app: apps/common-app in the repository.
  • Example project instructions: the example README referenced in the repository.

Learn the API from the official documentation

The API references, conceptual guides and more are in the dedicated documentation pages. Use the Reanimated docs for animation APIs and the Worklets docs for the multi-threaded JavaScript side.

The Software Mansion Community Discord is listed in the README if you want to ask questions about Reanimated or Worklets.

  • Reanimated documentation: docs.swmansion.com/react-native-reanimated
  • Worklets documentation: docs.swmansion.com/react-native-worklets
  • Community Discord: discord.swmansion.com

What people use it for

  • Animated or gesture-heavy mobile screens in React Native apps.
  • Keeping animations smooth while the JavaScript side of the app is busy, using the multi-threaded execution that Worklets provides.
  • Adding interactions to screens in apps already running on the New React Native architecture.
  • Exploring the animation API by running the showcase app in the repository.

Frequently asked questions

Is react-native-reanimated free to use?

Yes. The README states that Reanimated and Worklets are licensed under The MIT License, which is listed as the project's licence. Check the LICENSE file in the repository for the full terms.

What does react-native-reanimated require?

You need a React Native project that uses the New React Native architecture for Reanimated 4.x. The library supports only the three latest React Native versions, so older setups should use the latest 3.x release.

Does react-native-reanimated work with the old React Native architecture?

Reanimated 4.x does not. The compatibility notes say 4.x and Worklets support only the New Architecture, and recommend staying on the latest 3.x release if your app still uses the old one.

Can I use react-native-reanimated in a plain web or Node project?

No. The library is for React Native mobile apps, and it is not meant for projects that do not use React Native.

What is react-native-worklets and do I need it?

React Native Worklets is a companion library in the same repository that enables multi-threaded JavaScript execution in React Native applications. The README gives separate installation instructions for it, so check the Worklets documentation to see how it fits your setup.

What are the alternatives to react-native-reanimated?

The project lists React Native Animated, react-native-gesture-handler, Moti and react-native-skia as comparable projects. Compare them against your needs for animations, gestures and performance.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Reanimated suits React Native developers who are on the New Architecture and need animated or gesture-heavy screens that stay smooth. Teams on the old architecture, projects without React Native, and beginners new to React Native should look at other options or learn the framework first.

Install options & downloads