react-native-reanimated - Amazon Vega Docs

The React Native Reanimated library extends the Animated library API and provides greater flexibility when using gesture-based interactions. With Reanimated, you can easily create smooth animations and interactions that run on the UI thread.

Documentation

For more information about this library and its API, see https://docs.swmansion.com/react-native-reanimated/ in the official Software Mansion documentation.

Installation

Select the tab for your React Native version. Note that RN 0.83 requires the additional @amazon-devices/react-native-worklets dependency, which provides the core multithreading infrastructure that enables worklets — JavaScript functions that can be executed on separate threads (like the UI thread). Worklets are the foundation that allows Reanimated to run animations and interactions smoothly without blocking the JavaScript thread.

Add the JavaScript library dependency in the package.json file:

React Native 0.72
React Native 0.83

"dependencies": {
      ...
      "@amazon-devices/react-native-reanimated": "~2.0.0",
}

"dependencies": {
      ...
      "@amazon-devices/react-native-worklets": "~1.0.0",
      "@amazon-devices/react-native-reanimated": "~4.0.0",
}

Add the Reanimated Babel plugin to your babel.config.js:

 module.exports = {
   plugins: [
     ...
     '@amazon-devices/react-native-worklets/plugin',
   ],
 };

Run the following command to clear the Metro bundler cache:
npm start --reset-cache
Reinstall the package-lock.json file by running the npm install command.

For additional information and context, see installation in the Software Mansion documentation.

Examples

The following example shows how to run a simple animation in an infinite loop using the withTiming method.

import React from 'react';
import { StyleSheet, View } from 'react-native';
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withTiming,
  withRepeat,
} from '@amazon-devices/react-native-reanimated';

export function App() {
  const offset = useSharedValue(200);

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

  React.useEffect(() => {
    offset.value = withRepeat(
      withTiming(-offset.value, { duration: 1500 }),
      -1,
      true
    );
  }, []);

  return (
    <View style={styles.container}>
      <Animated.View style={[styles.box, animatedStyles]} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    height: '100%',
  },
  box: {
    height: 120,
    width: 120,
    backgroundColor: '#b58df1',
    borderRadius: 20,
  },
});

The following example shows how run a spring-based animation using the withSpring function:

import React from 'react';
import { StyleSheet, View } from 'react-native';
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
  withRepeat,
} from '@amazon-devices/react-native-reanimated';

const initialOffset = 200;

export function App() {
  const offset = useSharedValue(initialOffset);

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

  React.useEffect(() => {
    offset.value = withRepeat(withSpring(-offset.value), -1, true);
  }, []);

  return (
    <View style={styles.container}>
      <Animated.View style={[styles.box, animatedStyles]} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    alignItems: 'center',
    justifyContent: 'center',
    height: '100%',
  },
  box: {
    height: 120,
    width: 120,
    backgroundColor: '#b58df1',
    borderRadius: 20,
  },
});

API support

The reanimated library on Vega provides a Turbo Module which adds a support for most of methods listed below.

Animations

Method	Description
`withTiming`	Creates an animation based on duration and easing.
`withSpring`	Creates spring-based animations.
`withDecay`	Creates animations that mimic objects in motion with friction. The animation starts with the provided velocity and slows down over time according to the given deceleration rate until it stops.
`withSequence`	An animation modifier that runs animations in a sequence.
`withRepeat`	An animation modifier that repeats an animation a number of times or runs it indefinitely.
`withDelay`	An animation modifier that starts an animation with a delay.
`withClamp`	An animation modifier that lets you limit the scope of movement of your animation to make it stay within some predefined range.

Core

Method	Description
`useSharedValue`	Defines shared values in your components.
`useAnimatedStyle`	Creates a styles object, similar to the `StyleSheet` styles, which can be animated.
`useAnimatedProps`	Creates an animated props object, which can be animated using shared values.
`useAnimatedRef`	Gets a reference of a view. Used alongside the `scrollTo` and `useScrollViewOffset` functions.
`useDerivedValue`	Create new shared values based on existing ones, while keeping them reactive.
`createAnimatedComponent`	Creates an Animated version of any React Native component. Wrapping a component with `createAnimatedComponent` allows Reanimated to animate any prop or style associated with that component.
`cancelAnimation`	Cancels a running animation paired to a shared value.

Scroll

Method	Description
`scrollTo`	Provides synchronous scroll on the UI thread to a given offset, using an animated reference to a scroll view. Performs smooth scrolling without lags.
`useScrollViewOffset`	Creates animations based on the offset of a `ScrollView`. The hook automatically detects if the `ScrollView` is horizontal or vertical.
`useAnimatedScrollHandler`	A convenience hook that returns an event handler reference, which can be used with React Native’s scrollable components.

Device

Method	Description
`useAnimatedSensor`	Creates animations based on data from the device’s sensors: accelerometer, gyroscope, gravity, magnetic field, and rotation.
`useReducedMotion`	Queries the reduced motion system setting.

Threading

Method	Description
`runOnJS`	Asynchronously runs nonworkletized functions that can’t run on the UI thread.
`runOnUI`	Asynchronously runs workletized functions on the UI thread.
`createWorkletRuntime`	Creates a new JS runtime used to run worklets possibly on different threads than a JS or UI thread.

workletize

Workletize means to convert a JavaScript function into a serializable object which can be copied and ran on a UI thread. Functions are marked with “worklet”. Directives are automatically picked up and workletized by the Reanimated Babel plugin.

Utilities

Method	Description
`interpolate`	Maps a value from one range to another using linear interpolation.
`clamp`	Limits a value within a specified range.
`interpolateColor`	Maps input range to output colors using linear interpolation.
`getRelativeCoords`	Determines the location on the screen, relative to the given view.

Advanced APIs

Method	Description
`measure`	Synchronously gets the dimensions and position of a view on the screen, on the UI thread.
`useAnimatedReaction`	Responds to changes in a shared value.
`useFrameCallback`	Runs a function on every frame update.
`useEvent`	A low-level hook, returning an event handler that’s invoked with native events. Used to create custom event handler hooks like `useAnimatedGestureHandler` or `useAnimatedScrollHandler`.
`useHandler`	A low-level hook, returning a context object and value, indicating whether worklet should be rebuilt. Used to create custom event handler hooks like `useAnimatedGestureHandler` or `useAnimatedScrollHandler`.
`dispatchCommand`	Dispatches a command on a native component synchronously from the UI thread.
`setNativeProps`	Updates component properties.
`useComposedEventHandler`	Lets you compose `useEvent`-based event handlers (such as `useAnimatedScrollHandler` or your own custom ones) into a single, combined event handler.
`makeMutable`	Internally used by the `useSharedValue` hook to create a shared value.

Exceptions

The reanimated library on Vega has a few exceptions in terms of API support. Vega doesn’t support the following hooks and methods:

useAnimatedSensor
useAnimatedKeyboard
useReducedMotion
Layout Animations on Fabric

CSS Transitions
CSS Animations

SETs (Shared Element Transitions)

Known Issues on Vega

Animations that use withRepeat stop repeating after fast refresh is used.
Style does not update on the animation after fast refresh is used.

Supported versions

NPM package version	Vega SDK version	Vega OS version	React Native version
~2.0.x+3.5.4	0.23 and earlier	`OS 1.1 (1401010009820)` and earlier	0.72
~4.0.x+4.1.3	0.24	`OS 1.2 (2101020054720)`	0.72, 0.83

Additional Resources

For information on other libraries, see Supported Third-Party Libraries and Services.

Credits

This project has been built and is maintained thanks to the support from Shopify, Expo.io, and Software Mansion.

​Documentation

​Installation

​Examples

​API support

​Animations

​Core

​Scroll

​Device

​Threading

​workletize

​Utilities

​Advanced APIs

​Exceptions

​Known Issues on Vega

​Supported versions

​Additional Resources

​Credits