# react-native-reanimated
### Create Smooth Animations with an Excellent Developer Experience
#### Why Choose Reanimated?
##### Declarative API
Reanimated offers a declarative approach to creating animations, simplifying complexity from numerous methods down to just a few. Define the desired animation outcome and let Reanimated handle the style and property animations for you.
##### High Performance
With Reanimated, define animations in plain JavaScript that run natively on the UI thread by default. This ensures smooth interactions up to 120 fps or more, delivering a native experience users expect.
##### Rich Features
Reanimated's capabilities extend beyond animating simple views or images. Integrate your animations with device sensors or keyboards, utilize Layout Animations, and effortlessly animate elements between navigation screens.
- **Learn More**: Discover the features of Reanimated 3 in our latest article.
- [See blog post](#)
##### Animation Capabilities
Animate every React Native prop on iOS, Android, and the Web up to 120 fps.
```typescript
function App() {
const width = useSharedValue(100);
const handlePress = () => {
width.value = withSpring(width.value + 50);
};
return
);
}
```
##### Layout Animations
Automatically animate views when they are added or removed from the view hierarchy.
```typescript
function App() {
return navigation.navigate('Two')} />
);
}
function Two({ navigation }) {
return (
<>
navigation.navigate('One')} />
);
}
export default function SharedElementExample() {
return (
);
}
```
### Overview
When Reanimated detects a component with a `sharedTransitionTag` being mounted or unmounted, it searches for the last registered view with the same tag. If two matching components are found, their styles are captured and both views are temporarily moved to a transition container during the animation. Afterward, they return to their original parent.
Without custom animations, properties like `width`, `height`, `originX`, `originY`, and `transformMatrix` animate by default over 500ms using `withTiming`.
### Implementation
To create a shared transition between components on different screens, assign the same `sharedTransitionTag`. Unique tags are required for multiple shared views on the same screen.
**Screen A**
```typescript
goToDetails('countryside')}>
goToDetails('florence')}>
goToDetails('dawn')}>
```
### Remarks
- Only the native stack is supported.
- Animatable properties include `width`, `height`, `originX`, `originY`, and `transformMatrix`.
- Layout for shared view children isn't computed during transitions.
- Currently supports only the old React Native architecture (Paper).
- Future support for the new React Native architecture (Fabric) is planned.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|❌|
## Troubleshooting
### Initialization Issues
Reanimated consists of four core components that must align within the same minor version:
- C++
- Java
- JavaScript
- Reanimated Babel plugin.
Discrepancies in these components, especially when transpiled with different versions of the Reanimated Babel plugin, can lead to undefined behavior and errors.
#### Failed to Create a Worklet
**Problem:** This typically occurs if Reanimated is not installed correctly, such as omitting the Reanimated Babel plugin from `babel.config.js`.
**Solution:** Refer to the installation documentation at [Reanimated Getting Started](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/#step-2-add-reanimateds-babel-plugin) for guidance.
#### Native Part of Reanimated Doesn't Seem to Be Initialized
**Problem:** This issue arises when the native side of Reanimated fails to initialize from JavaScript.
**Solution:**
1. Ensure your app is rebuilt after installing or upgrading Reanimated.
1. Verify that your platform is supported by Reanimated, including:
- Android
- iOS
- macOS
- tvOS
- visionOS
- Web
1. For brownfield apps, manually initialize the native library.
#### Unknown Version of Reanimated Babel Plugin
**Problem:** This occurs when the JavaScript side cannot retrieve the version of the Reanimated Babel plugin.
**Solution:**
1. Check if any part of your code is transpiled with an outdated version of the Reanimated Babel plugin.
1. Ensure you are not using a release bundle with a debug build, as this is unsupported.
#### Mismatch Between JavaScript Code Version and Reanimated Babel Plugin Version
**Problem:** This can happen when code is transpiled with an outdated version of the Reanimated Babel plugin.
**Solution:** Reset your Metro bundler cache using `yarn start --reset-cache`, `npm start -- --reset-cache`, or `expo start -c` and rerun the app. If issues persist, identify dependencies that may contain outdated worklets by examining error messages.
#### Using Dev Bundle in a Release App Build is Not Supported
**Problem:** This occurs when a release build uses a development JavaScript bundle.
**Solution:** Refer to relevant documentation for more information.
#### Couldn't Determine the Version of the Native Part of Reanimated
**Problem:** This happens when Reanimated cannot determine its native part's version.
**Solution:** Ensure your app is rebuilt after upgrading `react-native-reanimated`. For Expo Go users, use the exact version bundled with the Expo SDK.
#### Mismatch Between JavaScript and Native Parts of Reanimated
**Problem:** This occurs when different versions of the JavaScript and native parts are used.
**Solution:** Confirm that your app is rebuilt post-upgrade. For Expo Go, ensure compatibility with the bundled version in the Expo SDK.
#### C++ Side Failed to Resolve JavaScript Code Version
See "Couldn't Determine the Version of the Native Part of Reanimated" and "Unknown Version of Reanimated Babel Plugin."
#### Mismatch Between C++ Code Version and JavaScript Code Version
Refer to issues regarding mismatches between JavaScript parts, native parts, and the Reanimated Babel plugin.
#### C++ Side Failed to Resolve Java Code Version
**Problem:** This occurs when the version of the Java part cannot be determined, likely due to a missed rebuild after an upgrade.
**Solution:** Rebuild your app and check if the issue persists. If it does, consider reporting it on GitHub.
#### Mismatch Between C++ Code Version and Java Code Version
Refer to "Native Side Failed to Resolve Java Code Version."
#### Java Side Failed to Resolve C++ Code Version
**Problem:** This happens when the version of the C++ part cannot be determined, likely due to a missed rebuild after an upgrade.
**Solution:** Refer to "Native Side Failed to Resolve Java Code Version."
#### Mismatch Between Java Code Version and C++ Code Version
Refer to "Native Side Failed to Resolve Java Code Version."
#### Multiple Versions of Reanimated Were Detected
**Problem:** This error occurs when more than one instance of Reanimated exists in your project, often due to dependencies installing it within their own `node_modules`.
**Solution:**
- For Yarn users, add a `resolutions` property in `package.json`:
```json
"resolutions": {
"react-native-reanimated": ""
}
```
- For npm users, use the `overrides` property:
```json
"overrides": {
"react-native-reanimated": ""
}
```
Afterward, run your package manager again (`yarn` or `npm install`).
#### Another Instance of Reanimated Was Detected
Refer to "Multiple Versions of Reanimated Were Detected."
#### Outdated Version of React Native for New Architecture
**Problem:** Reanimated supports the New Architecture (Fabric) only on the latest minor release of React Native.
**Solution:** Upgrade to a newer version of React Native or downgrade Reanimated. Consult the compatibility table for supported versions.
### Warnings
#### Reduced Motion Setting is Enabled on This Device
**Problem:** This warning helps avoid confusion when reduced motion is enabled.
**Solution:** Ignore this warning in development mode as it's safe. To disable, add:
```javascript
LogBox.ignoreLogs([
"[Reanimated] Reduced motion setting is enabled on this device.",
])
```
#### Tried to Modify Key of an Object Which Has Been Converted to a Shareable
**Problem:** This warning indicates that a shared value should be used or objects in worklets accessed more granularly.
##### 1. Not Using Shared Values
Example:
```javascript
const obj = { prop: 1 }
function worklet() {
"worklet"
console.log(obj.prop)
}
runOnUI(worklet)()
obj.prop = 2 // Warning occurs here.
runOnUI(worklet)()
```
**Solution:** Use a shared value instead:
```typescript
const sv = useSharedValue({ prop: 1 })
function worklet() {
"worklet"
console.log(sv.value.prop)
}
runOnUI(worklet)()
sv.value = { prop: 2 } // Correct usage.
```
##### 2. Not Accessing Object Properties Granularly
Example:
```javascript
const obj = { propAccessedInWorklet: 1, propNotAccessedInWorklet: 2 }
function worklet() {
"worklet"
console.log(obj.propAccessedInWorklet)
}
runOnUI(worklet)()
obj.propNotAccessedInWorklet = 3 // Warning occurs here.
```
**Solution:** Assign accessed properties to variables beforehand:
```typescript
const obj = { propAccessedInWorklet: 1, propNotAccessedInWorklet: 2 }
const propAccessedInWorklet = obj.propAccessedInWorklet
function worklet() {
"worklet"
console.log(propAccessedInWorklet)
}
runOnUI(worklet)()
obj.propNotAccessedInWorklet = 3 // Correct usage.
```
### Threading Issues
#### Tried to Synchronously Call a Non-Worklet Function on the UI Thread
**Problem:** This occurs when calling a non-worklet function from within a worklet.
Example:
```javascript
function callee() {
console.log("hello")
}
function caller() {
"worklet"
callee() // Error here.
}
runOnUI(caller)()
```
**Solution:**
1. Mark the function as a worklet using `worklet` directive:
```typescript
function callee() {
"worklet"
console.log("hello")
}
```
1. Execute the function on the JS thread with `runOnJS`:
```typescript
function caller() {
"worklet"
runOnJS(callee)()
}
```
For more information, refer to Reanimated's documentation on worklets.
## useAnimatedScrollHandler
The `useAnimatedScrollHandler` hook provides an event handler reference that can be utilized with React Native's scrollable components. This hook is part of the `react-native-reanimated` library.
### Reference
```typescript
import { useAnimatedScrollHandler } from 'react-native-reanimated';
function App() {
const offsetY = useSharedValue(0);
const scrollHandler = useAnimatedScrollHandler((event) => {
offsetY.value = event.contentOffset.y;
});
// ...
return void>,
dependencies?: any[]
) {
const { context, doDependenciesDiffer, useWeb } = useHandler(
handlers,
dependencies
)
return useEvent(
(event: any) => {
"worklet"
const { onPageScroll } = handlers
if (onPageScroll && event.eventName.endsWith("onPageScroll")) {
onPageScroll(event, context)
}
},
["onPageScroll"],
doDependenciesDiffer
)
}
```
#### Arguments
##### `handlers`
An object containing keys that correspond to native event names. The values should be individual worklets. Each worklet is triggered when its associated event is dispatched on the connected animated component.
Each event worklet receives:
- `event`: An event object whose payload varies based on the event type.
- `context`: A plain JavaScript object for storing state, persisting between events. This allows communication among multiple event handlers provided as an object of worklets.
##### `dependencies` (Optional)
An optional array of dependencies. This is relevant when using Reanimated without its Babel plugin in a web environment.
#### Returns
The hook returns:
- A context reused by event handlers.
- An indicator to determine if worklets should be rebuilt.
- A boolean, `useWeb`, to check for the web environment if different implementations are needed.
### Example
For simpler implementations, consider using `useScrollViewOffset`.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
This documentation provides a comprehensive overview of how to utilize the `useHandler` hook within React Native Reanimated for creating custom event handlers.
## Keyframe animations
Keyframes provide a schema for defining animations, offering more flexibility than standard Entering and Exiting presets. They allow you to create complex animations with ease.
### Reference
```typescript
import { Keyframe } from 'react-native-reanimated';
const keyframe = new Keyframe({
0: {
transform: [{ rotate: '0deg' }],
},
45: {
transform: [{ rotate: '100deg' }],
easing: Easing.exp,
},
100: {
transform: [{ rotate: '45deg' }],
},
});
function App() {
return
);
}
```
Avoid directly modifying shared values without using the `.value` property, as in `sv.value = sv.value + 100`.
### Using an Animation Function
To animate smoothly, import and use the `withSpring` function. Wrap it around the new width value to create a spring animation:
```typescript
import { Button, View } from 'react-native';
import Animated, { useSharedValue, withSpring } from 'react-native-reanimated';
export default function App() {
const width = useSharedValue(100);
const handlePress = () => {
width.value = withSpring(width.value + 50);
};
return (
);
}
```
This creates a bouncy spring animation for the element's width.
### Summary
In this section, you learned about:
- `Animated` components to define animatable elements.
- Shared values as the driving factor of animations using `useSharedValue`.
- Accessing and modifying shared values via their `.value` property (e.g., `sv.value = 100;`).
- Creating smooth animations by modifying shared values with functions like `withSpring`.
### What's Next?
In the next section, you'll explore animating styles and props using `useAnimatedStyle` and `useAnimatedProps` hooks.
## Layout transitions
Layout transitions enable smooth animations during layout changes, which may involve alterations in size and position. Both aspects can be animated for a seamless experience.
### Predefined Transitions
This section outlines the available predefined layout transitions along with their animation modifiers.
#### Linear Transition
The linear transition animates both position and dimension uniformly.
##### Reference
```typescript
import { LinearTransition } from 'react-native-reanimated';
function App() {
return
{show &&
);
}
```
#### Arguments
- **`skipEntering` (Optional)**: A boolean that determines if the entering animations of child components should be skipped when `LayoutAnimationConfig` is mounted.
- **`skipExiting` (Optional)**: A boolean that determines if the exiting animations of child components should be skipped when `LayoutAnimationConfig` is unmounted.
### Example Usage
```typescript
{outer && (
{inner && (
)}
```
### Remarks
- **Nesting**: The `LayoutAnimationConfig` component can be nested to disable animations for a specific subset of components.
- **FlatList Compatibility**: For `FlatList`, use the `skipEnteringExitingAnimations` prop. This automatically wraps your `FlatList` with `` to manage animations when the list is mounted or unmounted.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|❌|
- **Reference**
- Arguments
- **Example**
- **Remarks**
- **Platform Compatibility**
## Web Support
Reanimated can be launched in a web browser, with all functionalities implemented purely in JavaScript. This may result in lower animation efficiency compared to native implementations.
### Step 1: Install the Package
Install `@babel/plugin-proposal-export-namespace-from` using one of the following package managers:
- **EXPO**
```bash
npx expo install @babel/plugin-proposal-export-namespace-from
```
- **NPM**
```bash
npm install @babel/plugin-proposal-export-namespace-from
```
- **YARN**
```bash
yarn add @babel/plugin-proposal-export-namespace-from
```
### Step 2: Add Plugins to Config File
Update your `babel.config.js` by adding the following plugins:
```javascript
module.exports = {
presets: [
// Existing presets...
],
plugins: [
...,
'@babel/plugin-proposal-export-namespace-from',
'react-native-reanimated/plugin', // Ensure this is listed last
],
};
```
**Caution:** Make sure `react-native-reanimated/plugin` is the last plugin in the list.
### Step 3: Launch Your App
To start a playground app in the browser, use:
```bash
yarn web
```
For example applications from the Reanimated repository, execute these commands at the root of the repository:
```bash
yarn && yarn build
```
Then navigate to `apps/web-example` and run:
```bash
yarn start
```
### Webpack Support
To use Reanimated in a Webpack app, adjust your configuration as follows:
Example Webpack config with Reanimated support:
```javascript
const HtmlWebpackPlugin = require("html-webpack-plugin")
const webpack = require("webpack")
module.exports = {
entry: ["babel-polyfill", "./index.js"],
plugins: [
new HtmlWebpackPlugin({
filename: "index.html",
template: "./index.html",
}),
new webpack.EnvironmentPlugin({ JEST_WORKER_ID: null }),
new webpack.DefinePlugin({ process: { env: {} } }),
],
module: {
rules: [
{
test: /\.(js|jsx)$/,
use: {
loader: "babel-loader",
options: {
presets: [
"@babel/preset-react",
{ plugins: ["@babel/plugin-proposal-class-properties"] },
],
},
},
},
],
},
resolve: {
alias: { "react-native$": "react-native-web" },
extensions: [".web.js", ".js"],
},
}
```
### Web Without the Babel Plugin
Reanimated can be used without its Babel plugin by manually passing dependency arrays to hooks. This approach is valid for both web and native platforms.
Ensure these hooks include a dependency array as their last argument:
- `useDerivedValue`
- `useAnimatedStyle`
- `useAnimatedProps`
- `useAnimatedReaction`
Example usage:
```javascript
const sv = useSharedValue(0)
const dv = useDerivedValue(
() => sv.value + 1,
[sv] // dependency array here
)
```
**Caution:** Pass the root dependency (`sv`) rather than `sv.value`.
Babel users must still install the `@babel/plugin-proposal-class-properties` plugin.
#### ESLint Support
To add ESLint support for Reanimated hooks, update your ESLint configuration:
```json
{
"rules": {
"react-hooks/exhaustive-deps": [
"error",
{
"additionalHooks": "(useAnimatedStyle|useDerivedValue|useAnimatedProps)"
}
]
}
}
```
**Info:** This assumes the `react-hooks` ESLint plugin is installed.
If using ESLint autofix, manually correct any `.value` additions to dependency arrays:
```javascript
const sv = useSharedValue(0)
// 🚨 bad: sv.value in array
const dv = useDerivedValue(() => sv.value, [sv.value])
// ✅ good: sv in array
const dv = useDerivedValue(() => sv.value, [sv])
```
### Solito / Next.js Compatibility
An experimental SWC plugin is being developed. Until then, follow the "Web without a Babel Plugin" instructions.
#### Next.js Polyfill
To use Reanimated with Next.js/Solito, add the `raf` polyfill for `requestAnimationFrame`:
```bash
yarn add raf
```
Include this at the top of your `_app.tsx`:
```javascript
import "raf/polyfill"
```
## React Native Reanimated: List Layout Animations (Version 3.x)
### Overview
The `itemLayoutAnimation` feature in React Native Reanimated allows you to define layout transitions for list items when their layout changes. You can choose from predefined transitions like `LinearTransition`, or create custom ones.
#### Example Usage
```typescript
import Animated, { LinearTransition } from 'react-native-reanimated';
function App() {
return (
{/* Content goes here */}
);
}
```
#### Arguments
##### `animatedRef`
An animated reference linked to the `ScrollView` component you wish to monitor. This animated reference must be assigned either to an Animated component or a React Native built-in component.
##### `initialRef` (Optional)
A shared value that can optionally be updated with the scroll offset. If not provided, a new shared value will be created internally by default.
#### Returns
The hook returns a shared value representing the current offset of the `ScrollView`.
### Example Usage
- The `animatedRef` argument can be dynamically changed, and the hook will continue to provide accurate values based on the connected `ScrollView`. For instance:
```typescript
useScrollViewOffset(someState ? someScrollRefA : someScrollRefB)
```
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## Getting started
The *Fundamentals* section aims to establish a solid understanding of the core concepts of Reanimated, empowering you to explore more complex scenarios independently. This section includes interactive examples, code snippets, and detailed explanations.
### What is React Native Reanimated?
React Native Reanimated is an advanced animation library developed by Software Mansion. It enables developers to create smooth animations and interactions that run on the UI thread with ease.
### Quick Start
To begin a new project using Expo:
- **NPM**:
```bash
npx create-expo-app@latest my-app -e with-reanimated
```
- **YARN**:
```bash
yarn create expo-app my-app -e with-reanimated
```
Alternatively, explore examples available on GitHub.
### Installation
Adding Reanimated to your project involves three main steps:
#### Step 1: Install the Package
Install the `react-native-reanimated` package from npm:
- **EXPO**:
```bash
npx expo install react-native-reanimated
```
- **NPM**:
```bash
npm install react-native-reanimated
```
- **YARN**:
```bash
yarn add react-native-reanimated
```
#### Step 2: Add Reanimated's Babel Plugin
Include the `react-native-reanimated/plugin` in your `babel.config.js`:
```javascript
module.exports = {
presets: [
// existing presets
],
plugins: [
// other plugins,
"react-native-reanimated/plugin",
],
}
```
**Caution**: Ensure that `react-native-reanimated/plugin` is the last plugin listed.
#### Step 3: Wrap Metro Config with Reanimated Wrapper (Recommended)
Modify your `metro.config.js` to wrap the existing configuration using `wrapWithReanimatedMetroConfig`:
```javascript
// metro.config.js
const {
wrapWithReanimatedMetroConfig,
} = require("react-native-reanimated/metro-config")
const config = {
// Your existing Metro configuration options
}
module.exports = wrapWithReanimatedMetroConfig(config)
```
#### Step 4: Clear Metro Bundler Cache (Recommended)
- **EXPO**:
```bash
npx expo start -c
```
- **NPM**:
```bash
npm start -- --reset-cache
```
- **YARN**:
```bash
yarn start --reset-cache
```
#### Expo Development Build
For an Expo development build, update the native code in `ios` and `android` directories by running:
```bash
npx expo prebuild
```
#### Platform-Specific Setup
##### Android
No additional setup is required.
##### iOS
Before running your app on iOS, install pods with:
```bash
cd ios && pod install && cd ..
```
##### Web
For web-targeted apps using react-native-web, it's recommended to use Expo. Install and add `@babel/plugin-proposal-export-namespace-from` Babel plugin in your `babel.config.js`:
- **EXPO**:
```bash
npx expo install @babel/plugin-proposal-export-namespace-from
```
- **NPM**:
```bash
npm install @babel/plugin-proposal-export-namespace-from
```
- **YARN**:
```bash
yarn add @babel/plugin-proposal-export-namespace-from
```
Ensure your `babel.config.js` includes:
```javascript
module.exports = {
presets: [
// existing presets
],
plugins: [
"@babel/plugin-proposal-export-namespace-from",
"react-native-reanimated/plugin",
],
}
```
**Note**: The `react-native-reanimated/plugin` should be listed last.
For more advanced scenarios, such as using Reanimated with `webpack` or `Next.js`, refer to the separate Web Support guide.
## withSpring
`withSpring` enables the creation of spring-based animations in your application.
### Reference
```typescript
import { withSpring } from "react-native-reanimated"
function App() {
sv.value = withSpring(0)
// ...
}
```
#### Arguments
##### `toValue`
The target value where the animation will settle. Supported categories include:
- **Numbers**: Can be a number or a string representation of a number.
- **Suffixed Numbers**: Strings that combine numbers and units (e.g., `"5.5%"`, `"90deg"`) without spaces, using basic English letters for suffixes.
- **Colors**:
- Hexadecimal integer: e.g., `0xff1234`
- RGB: e.g., `"rgb(100, 50, 0)"`
- RGBA: e.g., `"rgba(255, 105, 180, 0.5)"`
- RGB Hexadecimal: e.g., `"#53575E"`
- HSL: e.g., `"hsl(0, 50%, 50%)"`
- Named colors: e.g., `"dodgerblue"`
- **Objects**: Objects with properties that will be animated individually.
- **Array**: Arrays of numbers where each value is animated separately.
- **Transformation Matrix**: An array of exactly 16 numerical values treated as a transformation matrix, decomposed into rotation, scale, and translation for separate animation.
Note: The `toValue` must match the category of the animated shared value (e.g., animating `width` from `100px` to `50%` is not allowed).
##### `config` (Optional)
Configuration options for spring animations:
**Physics-based Spring Configuration:**
|Name|Type|Default|Description|
|-|-|-|-|
|mass (optional)|`number`|1|The weight of the spring. Lower values make the animation faster.|
|damping (optional)|`number`|10|Controls how quickly a spring slows down; higher values result in quicker rest.|
**Duration-based Spring Configuration:**
|Name|Type|Default|Description|
|-|-|-|-|
|duration (optional)|`number`|2000|Length of the animation in milliseconds. Available in Reanimated ≥ 3.2.x.|
|dampingRatio (optional)|`number`|0.5|Determines how damped the spring is; `1` means critically damped, and values >1 mean overdamped. Available in Reanimated ≥ 3.2.x.|
**Note**: The `mass` and `damping` properties cannot be used simultaneously with `duration` and `dampingRatio`. When both are provided, `duration` and `dampingRatio` take precedence.
**Common Spring Configuration:**
|Name|Type|Default|Description|
|-|-|-|-|
|stiffness (optional)|`number`|100|Determines the bounciness of the spring.|
|velocity (optional)|`number`|0|Initial velocity applied to the spring equation.|
|overshootClamping (optional)|`boolean`|false|Prevents the spring from bouncing over the `toValue`.|
|restDisplacementThreshold (optional)|`number`|0.01|Displacement below which the spring will settle at `toValue`.|
|restSpeedThreshold (optional)|`number`|2|Speed threshold in pixels per second for settling at `toValue`.|
|reduceMotion (optional)|`ReduceMotion`|`ReduceMotion.System`|Determines animation response to reduced motion settings. Available in Reanimated ≥ 3.5.x.|
|clamp (optional)|`[number, number]`|`undefined`|Limits the movement scope; reduces bounciness if exceeded. Available in Reanimated ≥ 3.6.x.|
##### `callback` (Optional)
A function executed upon animation completion. If the animation is canceled, it receives `false`; otherwise, it receives `true`.
#### Returns
`withSpring` returns an animation object representing the current state of the animation. This can be directly assigned to a shared value or used in a style object from `useAnimatedStyle`.
### Example
### Remarks
- The callback provided as the third argument is automatically workletized and executed on the UI thread.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## useAnimatedRef
The `useAnimatedRef` hook provides a way to obtain a reference to a view, which can be used in conjunction with functions like `measure`, `scrollTo`, and `useScrollViewOffset`.
To utilize this hook, you must assign the object created by `useAnimatedRef` to the `ref` property of a component.
### Reference
```typescript
import { useAnimatedRef } from 'react-native-reanimated';
function App() {
const animatedRef = useAnimatedRef();
return ();
return (
{
// Access the component reference
const component = animatedRef.current;
}}
/>
);
}
```
### Remarks
- `useAnimatedRef` can be used to reference not only Animated components but any React Native component.
- The value in the `current` property is available after the component has been mounted.
```typescript
function App() {
const animatedRef = useAnimatedRef();
console.log(animatedRef.current); // 🚩 Returns null
useEffect(() => {
console.log(animatedRef.current); // ✅ Returns the component
}, []);
return
);
}
```
To customize shared value changes based on user input, `useAnimatedStyle` is used for more control and flexibility:
```typescript
export default function App() {
const translateX = useSharedValue(0);
const handlePress = () => {
translateX.value += 50;
};
const animatedStyles = useAnimatedStyle(() => ({
transform: [{ translateX: withSpring(translateX.value * 2) }],
}));
return (
<>
);
}
```
`useAnimatedStyle` allows access to the shared value's `.value`, enabling operations like multiplication before assigning it to `style`. It also centralizes animation logic.
### Animating Props
While many values are animated via the `style` property, sometimes props need animating. For example, SVG elements use props instead of styles:
```typescript
);
}
```
For encapsulating animation logic and accessing `.value`, `useAnimatedProps` is used:
```typescript
const AnimatedCircle = Animated.createAnimatedComponent(Circle);
export default function App() {
const r = useSharedValue(20);
const handlePress = () => {
r.value += 10;
};
const animatedProps = useAnimatedProps(() => ({
r: withTiming(r.value),
}));
return (
);
}
```
In `useAnimatedProps`, return an object with animatable props, then pass it to the `animatedProps` prop of an Animated component.
### Summary
- Inline styles are simple but limited for complex animations.
- Props differ from styles as they aren't passed via the `style` object.
- `useAnimatedStyle` and `useAnimatedProps` provide access to shared values' `.value`, enhancing animation control.
- Custom animatable components can be created with `Animated.createAnimatedComponent`.
### What's Next?
In the next section, we'll delve into animation functions and customizing their behavior.
## useDerivedValue
The `useDerivedValue` function allows for the creation of new reactive shared values derived from existing ones. This ensures that any changes in the original shared values automatically update the derived value.
### Reference
```typescript
import { useDerivedValue } from "react-native-reanimated"
function App() {
const derivedValue = useDerivedValue(() => {
return sv.value * 50
})
}
```
#### Arguments
##### `updater`
A function that returns a new value constructed using shared values, React state, or other JavaScript values. This function is invoked whenever any of the shared values or states it depends on change.
##### `dependencies` (Optional)
An optional array specifying dependencies. This parameter is only relevant when Reanimated is used without its Babel plugin in web environments.
#### Returns
The `useDerivedValue` function returns a new, readonly shared value that reflects changes based on the output of the `updater` function.
### Example
### Remarks
- The callback provided to the first argument is automatically workletized and executed on the UI thread.
- You can use `useDerivedValue` without returning a value in the `updater` function to respond to changes in a shared value. For accessing previous values stored in a shared value, consider using `useAnimatedReaction`.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## runOnUI
The `runOnUI` function allows you to asynchronously execute workletized functions on the UI thread. It is commonly used within an `useEffect` for initiating animations upon component mount or unmount, as well as with `measure` and `scrollTo` functions that are implemented solely on the UI thread.
### Reference
```typescript
import { runOnUI } from "react-native-reanimated"
function App() {
// Example usage in an event handler or effect
runOnUI((greeting: string) => {
console.log(`${greeting} from the UI thread`)
})("Howdy")
// ...
}
```
#### Arguments
##### fn
A reference to a function intended for execution on the UI thread, originating from the JavaScript thread. Any arguments required by your function must be passed to the function returned by `runOnUI`, e.g., `runOnUI(myWorklet)(10)`.
#### Returns
`runOnUI` returns a function that accepts arguments for the initially provided function.
**Note:** Ensure you invoke the function returned from `runOnUI`.
### Example
### Remarks
- When creating animations, prioritize more general solutions such as `useDerivedValue`, `useAnimatedReaction`, or executing code within gesture callbacks. Resort to using `runOnUI` only after exploring these alternatives.
- A common error is attempting to execute a function inside of `runOnUI` like this: ~~`runOnUI(myWorklet(10))()`~~. The correct usage should be `runOnUI(myWorklet)(10)`.
- The callback provided as an argument is automatically workletized, making it ready for execution on the UI thread.
- Avoid executing `runOnUI` directly on the UI thread to prevent errors.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## runOnRuntime
The `runOnRuntime` function allows you to execute workletized functions asynchronously on a separate worklet runtime, which operates on a different thread.
### Reference
```typescript
import { createWorkletRuntime, runOnRuntime } from "react-native-reanimated"
const workletRuntime = createWorkletRuntime("background")
function App() {
// Example usage in an event handler or effect
runOnRuntime(workletRuntime, (greeting) => {
console.log(`${greeting} from a separate thread`)
})("Howdy")
// ...
}
```
#### Arguments
##### workletRuntime
A reference to the worklet runtime created using `createWorkletRuntime`.
##### fn
A function intended for execution on the UI thread from the JavaScript thread. The arguments for this function must be passed to the function returned by `runOnUI`, e.g., `runOnUI(myWorklet)(10)`.
#### Returns
`runOnRuntime` returns a function that accepts arguments for the function provided as its first argument.
**Note:** Ensure you call the function returned from `runOnRuntime`.
### Remarks
- A common mistake is to execute a function inside of `runOnRuntime` incorrectly, such as: ~~`runOnRuntime(myWorklet(10))()`~~. The correct usage is `runOnRuntime(myWorklet)(10)`.
- The callback passed as an argument will not be automatically workletized. You must manually add the `'worklet';` directive to enable execution on the UI thread.
- `runOnRuntime` can be called on any runtime, including the RN runtime, UI runtime, and other worklet runtimes.
- The function provided to `runOnRuntime` is added to an execution queue on a separate thread and executed asynchronously on the specified worklet runtime. Functions are executed in the order they were queued.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|❌|
## Applying modifiers
Reanimated provides built-in modifiers for customizing animations: `withRepeat`, `withSequence`, and `withDelay`. This guide demonstrates how to use these modifiers by creating a shake animation.
### Starting Point
We'll create an animated box that shakes on button press after a delay. The setup involves using `useAnimatedStyle` and the `withTiming` function to move the box 40px to the right smoothly.
```typescript
export default function App() {
const offset = useSharedValue(0);
const style = useAnimatedStyle(() => ({
transform: [{ translateX: offset.value }],
}));
const OFFSET = 40;
const handlePress = () => {
offset.value = withTiming(OFFSET);
};
return (
);
}
```
### Repeating an Animation
To create a shake effect, use the `withRepeat` modifier. This allows you to repeat an animation multiple times or indefinitely.
```typescript
import { withRepeat } from "react-native-reanimated"
function App() {
sv.value = withRepeat(withTiming(50), 5)
}
```
Pass a number for repetitions or a non-positive value for infinite repetition. Use `true` as the third argument to reverse the animation direction.
Updated example:
```typescript
export default function App() {
const offset = useSharedValue(0);
const style = useAnimatedStyle(() => ({
transform: [{ translateX: offset.value }],
}));
const OFFSET = 40;
const handlePress = () => {
offset.value = withRepeat(withTiming(OFFSET), 5, true);
};
return (
);
}
```
### Running Animations in a Sequence
To enhance the animation, use `withSequence` to chain animations. This modifier starts the next animation when the previous one ends.
```typescript
import { withSequence } from "react-native-reanimated"
function App() {
sv.value = withSequence(withTiming(50), withTiming(0))
}
```
Improved example:
```typescript
const TIME = 250
const handlePress = () => {
offset.value = withSequence(
// start from -OFFSET
withTiming(-OFFSET, { duration: TIME / 2 }),
// shake between -OFFSET and OFFSET 5 times
withRepeat(withTiming(OFFSET, { duration: TIME }), 5, true),
// go back to 0 at the end
withTiming(0, { duration: TIME / 2 })
)
}
```
### Starting the Animation with Delay
Add suspense by delaying the animation start using `withDelay`.
```typescript
import { withDelay } from "react-native-reanimated"
function App() {
sv.value = withDelay(500, withTiming(0))
}
```
Final example:
```typescript
const OFFSET = 40
const TIME = 250
const DELAY = 400
const handlePress = () => {
offset.value = withDelay(
DELAY,
withSequence(
// start from -OFFSET
withTiming(-OFFSET, { duration: TIME / 2 }),
// shake between -OFFSET and OFFSET 5 times
withRepeat(withTiming(OFFSET, { duration: TIME }), 5, true),
// go back to 0 at the end
withTiming(0, { duration: TIME / 2 })
)
)
}
```
### Summary
- **Modifiers**: `withRepeat`, `withSequence`, and `withDelay`.
- **`withRepeat`**: Repeats an animation a specified number of times or indefinitely.
- **`withSequence`**: Chains animations to run sequentially.
- **`withDelay`**: Delays the start of an animation.
### What's Next?
Explore handling `Tap` and `Pan` gestures, and learn about the `withDecay` animation function.
## withDecay
The `withDecay` function allows you to create animations that simulate objects moving under friction. These animations begin at a specified velocity and gradually slow down according to the provided deceleration rate until they come to a stop.
### Reference
```typescript
import { withDecay } from "react-native-reanimated"
function App() {
sv.value = withDecay({ velocity: 1 })
// ...
}
```
#### Arguments
##### `config`
Configuration for the decay animation. The following properties are available:
|Name|Type|Default|Description|
|-|-|-|-|
|`velocity` (optional)|`number`|0|Initial velocity of the animation.|
|`deceleration` (optional)|`number`|0.998|Rate at which the velocity decreases over time.|
|`clamp` (optional)\*|`[number, number]`|\[]|Array specifying bounds to restrict the animation's range. The animation stops when either bound is reached unless `rubberBandEffect` is set to `true`. \*Required if `rubberBandEffect` is enabled.|
|`velocityFactor` (optional)|`number`|1|Multiplier for velocity.|
|`rubberBandEffect` (optional)|`boolean`|false|Enables bouncing over the limit specified in `clamp`.|
|`rubberBandFactor` (optional)|`number`|0.6|Determines the strength of the rubber band effect.|
|`reduceMotion` (optional)|`ReduceMotion`|`ReduceMotion.System`|Controls how the animation responds to the device's reduced motion accessibility setting.|
##### `callback` (Optional)
A function executed upon animation completion. If the animation is canceled, the callback receives `false`; otherwise, it receives `true`.
#### Returns
The `withDecay` function returns an animation object representing the current state of the animation. This object can be directly assigned to a shared value or used as a style object returned from `useAnimatedStyle`.
### Example
*Note: An example section is mentioned but not provided in the original content.*
### Remarks
- The callback passed as the second argument is automatically workletized and executed on the UI thread.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## createAnimatedComponent
The `createAnimatedComponent` function enables the creation of an Animated version of any React Native component. By wrapping a component with `createAnimatedComponent`, Reanimated can animate any prop or style associated with that component.
Reanimated includes five built-in Animated components:
- `Animated.FlatList`
- `Animated.Image`
- `Animated.View`
- `Animated.ScrollView`
- `Animated.Text`
To animate other React Native components, they must be wrapped using the `createAnimatedComponent` function.
### Reference
```typescript
import Animated from "react-native-reanimated"
import { TextInput } from "react-native"
const AnimatedTextInput = Animated.createAnimatedComponent(TextInput)
```
#### Arguments
##### `component`
The component you wish to make animatable. Function components must be wrapped with `React.forwardRef()`.
#### Returns
`createAnimatedComponent` returns a component that Reanimated can animate.
### Example
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## createWorkletRuntime
The `createWorkletRuntime` function allows for the creation of a new JavaScript runtime that can execute worklets on threads separate from the main JavaScript or UI thread. This functionality is intended primarily for use by third-party libraries integrating with worklets. The returned value represents this runtime and should be communicated to the C++ side via JSI (JavaScript Interface) for further operations.
### Reference
#### Usage in JavaScript
```typescript
import { createWorkletRuntime } from "react-native-reanimated"
function App() {
const runtime = createWorkletRuntime("background")
}
```
#### Usage in C++
```cpp
auto runtime = reanimated::extractWorkletRuntime(rt, runtimeValue);
jsi::Runtime &rt = runtime->getJSIRuntime();
auto worklet = reanimated::extractShareableOrThrow(rt, workletValue);
runtime->runGuarded(worklet, ...args);
```
#### Arguments
- **`name`**: A string identifier for the runtime that will appear in device lists within Chrome DevTools.
- **`initializer`** (optional): A worklet executed synchronously on the same thread immediately after the runtime's creation. This can be used to inject global variables or functions into the runtime.
#### Returns
The `createWorkletRuntime` function returns a `WorkletRuntime`, which is represented as a `jsi::HostObject`.
### Remarks
- Worklet runtimes include built-in support for `performance.now` and `console.*` methods. Other APIs are not available by default and must be injected or captured via worklet closures.
- In development mode, unhandled errors thrown within the runtime (excluding those in the `initializer`) will be caught, logged to the console, and displayed in a LogBox.
- Chrome DevTools can be used for debugging the runtime when using Hermes. The runtime appears in the devices list as specified by the `name` argument passed to `createWorkletRuntime`.
- Shared values have limited support within worklet runtimes. To write to a shared value from the React Native (RN) runtime and read it on the worklet runtime, use `runOnRuntime`. Otherwise, updates will only reflect in the RN and UI runtimes.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|❌|
## interpolate
The `interpolate` function is used to map a numeric value from one specified range to another using linear interpolation.
### Reference Usage
```typescript
import { interpolate, Extrapolation } from "react-native-reanimated"
function App() {
const animatedStyle = useAnimatedStyle(() => ({
opacity: interpolate(sv.value, [0, 100], [0, 1], Extrapolation.CLAMP),
}))
}
```
#### Parameters
- **`value`**: A numeric value that will be mapped to the specified `output` range.
- **`input`**: An array of numbers defining the input range for interpolation.
- **`output`**: An array of numbers defining the output range for interpolation, which should have at least as many points as the input range.
- **`extrapolate` (Optional)**: Determines behavior when `value` is outside the `input` range. Defaults to `Extrapolation.EXTEND`.
Available options:
- `Extrapolation.EXTEND`: Predicts values beyond the output range.
- `Extrapolation.CLAMP`: Clamps the value to the edge of the output range.
- `Extrapolation.IDENTITY`: Returns the provided value unchanged.
String equivalents include `"extend"`, `"clamp"`, and `"identity"`.
To apply extrapolation to a specific edge, use an object:
```typescript
const opacity = interpolate(sv.value, [0, 100], [0, 1], {
extrapolateLeft: Extrapolation.CLAMP,
})
```
#### Return Value
The `interpolate` function returns a value mapped within the specified output range.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## cancelAnimation
The `cancelAnimation` function is used to stop an ongoing animation associated with a shared value in React Native Reanimated.
### Reference
```typescript
import { cancelAnimation } from "react-native-reanimated"
function App() {
const offset = useSharedValue(100)
const handleCancel = () => {
cancelAnimation(offset)
}
}
```
#### Arguments
- **`sharedValue`**: This is the shared value linked to an active animation that you wish to terminate. If no animation is currently running, `cancelAnimation` will have no effect.
#### Returns
The function returns `undefined`.
### Example Usage
To cancel an ongoing animation, simply call `cancelAnimation` with the relevant shared value as shown in the reference section above.
### Remarks
- You can restart a canceled animation by reassigning it to the same shared value using functions like `withSpring` or `withTiming`.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
This function is compatible across Android, iOS, and web platforms.
## Clamp Function in React Native Reanimated
The `clamp` function is used to restrict a value within a specified range, ensuring it does not exceed the defined minimum and maximum bounds.
### Reference
```typescript
import { clamp } from "react-native-reanimated"
function App() {
const result = clamp(sv.value, 0, 100)
}
```
#### Arguments
- **`value`**: A numeric value that will be returned if it falls within the specified `min` and `max` range.
- **`min`**: The lower bound. If the provided `value` is less than this number, `min` will be returned.
- **`max`**: The upper bound. If the provided `value` exceeds this number, `max` will be returned.
#### Returns
The function returns a numeric value that lies between the specified `min` and `max` bounds.
### Example Usage
```typescript
import { clamp } from "react-native-reanimated"
function App() {
const constrainedValue = clamp(150, 0, 100) // Result will be 100
}
```
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
This function is compatible across Android, iOS, and Web platforms.
## interpolateColor
The `interpolateColor` function maps an input range to output colors using linear interpolation. This is particularly useful in animations where you want a smooth transition between colors.
### Reference Example
```typescript
import { interpolateColor } from 'react-native-reanimated';
function App() {
const progress = useSharedValue(0);
const animatedStyle = useAnimatedStyle(() => {
return {
backgroundColor: interpolateColor(
progress.value,
[0, 1],
['red', 'green']
),
};
});
// ...
return {/* ... */}
);
}
```
#### Arguments
- **`animatedRef`**: An animated reference linked to the ScrollView (or another scrollable) component you wish to scroll. This animated reference must be passed to either an Animated component or a React Native built-in component.
- **`x`**: The pixel value for horizontal scrolling on the X axis.
- **`y`**: The pixel value for vertical scrolling on the Y axis.
- **`animated`**: A boolean indicating if the scroll should be smooth (`true`) or instant (`false`).
#### Returns
The `scrollTo` function returns `undefined`.
### Remarks
- The `scrollTo` function must be invoked from the UI thread.
- It supports `Animated.FlatList`.
- Typically works with other ScrollView-like and FlatList-like components if they use a `ScrollView` internally and are animated.
- Scrollable components need to implement the `getScrollableNode` method (and `getNativeScrollRef` for New Architecture) to be compatible with `scrollTo`.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## getRelativeCoords Functionality
The `getRelativeCoords` function is used to determine the screen location relative to a specified view.
### Reference Code
```typescript
import { getRelativeCoords } from 'react-native-reanimated';
const Comp = () => {
const animatedRef = useAnimatedRef();
const gestureHandler = useAnimatedGestureHandler({
onEnd: (event) => {
const coords = getRelativeCoords(
animatedRef,
event.absoluteX,
event.absoluteY
);
},
});
return (
);
};
```
### Arguments
- **`animatedRef`**: This is the result of `useAnimatedRef`, which extends a standard React ref to deliver the view tag on the UI thread. It should be passed as a prop to the view relative to which coordinates are needed.
- **`absoluteX`**: A number representing the absolute x-coordinate.
- **`absoluteY`**: A number representing the absolute y-coordinate.
### Returns
An object containing:
- `x`: The relative x-coordinate.
- `y`: The relative y-coordinate.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## useAnimatedGestureHandler
**Warning:**\
The `useAnimatedGestureHandler` hook allows for the creation of animations based on gesture handlers. It is essential to provide the object created by this hook to the `onGestureEvent` property of a gesture handler component.
This hook necessitates that `react-native-gesture-handler` be installed and configured within your project.
### Reference
```typescript
import { useAnimatedGestureHandler } from 'react-native-reanimated';
import { PanGestureHandler } from 'react-native-gesture-handler';
function App() {
const x = useSharedValue(0);
const gestureHandler = useAnimatedGestureHandler({
onStart: (_, ctx) => {
ctx.startX = x.value;
},
onActive: (event, ctx) => {
x.value = ctx.startX + event.translationX;
},
});
return (
);
}
```
#### Arguments
##### `gestureHandlers`
The primary argument is an object that can include one or more handlers. These handlers are set under the following keys: `onStart`, `onActive`, `onEnd`, `onFail`, `onCancel`, and `onFinish`.
Each handler will be activated based on the current state of the associated gesture handler. For further details, refer to the Gesture Handler documentation. The handler receives:
- `event` \[object] - an event object containing the payload specific to the type of gesture handler (e.g., `PanGestureHandler`, `RotationGestureHandler`).
- `context` \[object] - a JavaScript object for storing state information. This context can be read and modified, persisting between events and across handlers for all selected states.
##### `dependencies` (Optional)
An optional array of dependencies is relevant only when using Reanimated without the Babel plugin on the Web.
#### Returns
The `useAnimatedGestureHandler` hook returns a handler object that can be attached to gesture handler components from the `react-native-gesture-handler` library. This object must be passed to the `onGestureEvent` property of a gesture handler component.
### Example
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|⚠️|
- On the Web, it is necessary to pass the returned handler object to both `onGestureEvent` and `onHandlerStateChange` parameters.
## useScrollViewOffset Hook
The `useScrollViewOffset` hook enables the creation of animations based on a `ScrollView`'s offset. It automatically determines whether the `ScrollView` is oriented horizontally or vertically.
### Reference
```typescript
import { useAnimatedRef, useScrollViewOffset } from 'react-native-reanimated';
function App() {
const animatedRef = useAnimatedRef();
const scrollOffset = useScrollViewOffset(animatedRef);
return (
{/* Content goes here */}
);
}
```
#### Arguments
##### `animatedRef`
An animated reference linked to the `ScrollView` component you wish to monitor. This animated reference must be assigned either to an Animated component or a React Native built-in component.
##### `initialRef` (Optional)
A shared value that can optionally be updated with the scroll offset. If not provided, a new shared value will be created internally by default.
#### Returns
The hook returns a shared value representing the current offset of the `ScrollView`.
### Example Usage
- The `animatedRef` argument can be dynamically changed, and the hook will continue to provide accurate values based on the connected `ScrollView`. For instance:
```typescript
useScrollViewOffset(someState ? someScrollRefA : someScrollRefB)
```
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## measure
The `measure` function allows you to synchronously obtain the dimensions and position of a view on the screen, executed on the UI thread.
### Reference
```typescript
import { measure } from 'react-native-reanimated';
function App() {
const animatedRef = useAnimatedRef();
const handlePress = () => {
runOnUI(() => {
const measurement = measure(animatedRef);
if (measurement === null) {
return;
}
// Additional logic can be added here
})();
};
return
);
}
```
To customize shared value changes based on user input, `useAnimatedStyle` is used for more control and flexibility:
```typescript
export default function App() {
const translateX = useSharedValue(0);
const handlePress = () => {
translateX.value += 50;
};
const animatedStyles = useAnimatedStyle(() => ({
transform: [{ translateX: withSpring(translateX.value * 2) }],
}));
return (
<>
);
}
```
`useAnimatedStyle` allows access to the shared value's `.value`, enabling operations like multiplication before assigning it to `style`. It also centralizes animation logic.
### Animating Props
While many values are animated via the `style` property, sometimes props need animating. For example, SVG elements use props instead of styles:
```typescript
);
}
```
For encapsulating animation logic and accessing `.value`, `useAnimatedProps` is used:
```typescript
const AnimatedCircle = Animated.createAnimatedComponent(Circle);
export default function App() {
const r = useSharedValue(20);
const handlePress = () => {
r.value += 10;
};
const animatedProps = useAnimatedProps(() => ({
r: withTiming(r.value),
}));
return (
);
}
```
In `useAnimatedProps`, return an object with animatable props, then pass it to the `animatedProps` prop of an Animated component.
### Summary
- Inline styles are simple but limited for complex animations.
- Props differ from styles as they aren't passed via the `style` object.
- `useAnimatedStyle` and `useAnimatedProps` provide access to shared values' `.value`, enhancing animation control.
- Custom animatable components can be created with `Animated.createAnimatedComponent`.
### What's Next?
In the next section, we'll delve into animation functions and customizing their behavior.
## useFrameCallback in React Native Reanimated (Version: 3.x)
### Overview
The `useFrameCallback` hook allows you to execute a function on every frame update within your application.
### Reference
```typescript
import { useFrameCallback } from 'react-native-reanimated';
function App() {
const frameCallback = useFrameCallback((frameInfo) => {
// Increment a value with each frame update
sv.value += 1;
});
return (
frameCallback.setActive(!frameCallback.isActive)}
/>
);
}
```
#### Arguments
##### `callback`
- A function that runs on every frame update.
- Receives a `frameInfo` object with the following properties:
- `timestamp`: The system time (in milliseconds) when the last frame was rendered.
- `timeSincePreviousFrame`: Time (in milliseconds) since the previous frame. This is `null` for the first frame after activation and approximately 16 ms on a 60 Hz display or 8 ms on a 120 Hz display, assuming no frames are dropped.
- `timeSinceFirstFrame`: The time (in milliseconds) elapsed since the callback was activated.
##### `autostart` (Optional)
- Determines if the callback should start automatically. Defaults to `true`.
#### Returns
The `useFrameCallback` hook returns an object with these properties:
- `setActive`: A function to start or stop the frame callback.
- `isActive`: A boolean indicating whether the callback is currently running.
- `callbackId`: A unique identifier for the frame callback.
### Remarks
- The function provided in the `callback` argument is automatically workletized and executed on the UI thread.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
- Reference
- Arguments
- Returns
- Example
- Remarks
- Platform compatibility
## Handling gestures
This section covers handling gestures using Reanimated in conjunction with React Native Gesture Handler. We'll focus on `Tap` and `Pan` gestures and introduce the `withDecay` animation function.
Ensure you've completed the Gesture Handler installation steps before proceeding.
### Handling Tap Gestures
We begin with tap gestures, which detect brief screen touches. These can be used for custom buttons or pressable elements.
In this example, a circle grows and changes color upon touch.
First, wrap your app in `GestureHandlerRootView` to ensure gesture functionality:
```typescript
import { GestureHandlerRootView } from 'react-native-gesture-handler';
function App() {
return (
{/* rest of the app */}
);
}
```
Define tap gestures using `Gesture.Tap()` and chain methods like `onBegin`, `onStart`, `onEnd`, or `onFinalize` to update shared values:
```typescript
export default function App() {
const pressed = useSharedValue(false);
const tap = Gesture.Tap()
.onBegin(() => {
pressed.value = true;
})
.onFinalize(() => {
pressed.value = false;
});
```
Access shared values safely as gesture callbacks are automatically workletized.
Define animation logic using `withTiming` in `useAnimatedStyle`:
```typescript
const animatedStyles = useAnimatedStyle(() => ({
backgroundColor: pressed.value ? "#FFE04B" : "#B58DF1",
transform: [{ scale: withTiming(pressed.value ? 1.2 : 1) }],
}))
```
Pass the gesture to `GestureDetector` and apply `animatedStyles`:
```typescript
return (
);
}
```
### Handling Pan Gestures
Enhance the circle by making it draggable and bouncing back to its starting position upon release. Retain color highlight and scale effects.
Switch from `Tap` to `Pan` gesture and add an `onChange` method:
```typescript
const offset = useSharedValue(0);
const pan = Gesture.Pan()
.onBegin(() => {
pressed.value = true;
})
.onChange((event) => {
offset.value = event.translationX;
})
.onFinalize(() => {
offset.value = withSpring(0);
pressed.value = false;
```
Use `translationX` from the event data to move the circle. Reset `offset.value` in `onFinalize` using `withSpring`.
Adjust `useAnimatedStyle` for handling offset:
```typescript
const animatedStyles = useAnimatedStyle(() => ({
transform: [
{ translateX: offset.value },
{ scale: withTiming(pressed.value ? 1.2 : 1) },
],
backgroundColor: pressed.value ? "#FFE04B" : "#b58df1",
}))
```
### Using `withDecay`
`withDecay` retains gesture velocity for decelerating animations.
Pass final velocity in `onFinalize` to `withDecay`:
```typescript
const pan = Gesture.Pan()
.onChange((event) => {
offset.value += event.changeX;
})
.onFinalize((event) => {
offset.value = withDecay({
velocity: event.velocityX,
rubberBandEffect: true,
clamp: [
-(width.value / 2) + SIZE / 2 + BOUNDARY_OFFSET,
width.value / 2 - SIZE / 2 - BOUNDARY_OFFSET,
```
Ensure the square stays within screen bounds.
Explore `withDecay` API for more configuration options.
### Summary
This section covered gesture handling with Reanimated and Gesture Handler, focusing on `Tap`, `Pan`, and `withDecay`. Key points include:
- Integration of Reanimated with React Native Gesture Handler.
- Creation of gestures like `Gesture.Pan()` or `Gesture.Tap()`.
- Accessing shared values in gesture callbacks without extra boilerplate.
- Using `withDecay` for decelerating animations based on gesture velocity.
### What's Next?
Explore further gestures such as Pinch and Fling by reviewing the React Native Gesture Handler documentation. The next section will delve into a glossary of terms.
## withRepeat
`withRepeat` is an animation modifier that allows you to repeat a specified animation a certain number of times or indefinitely.
### Reference
```typescript
import { withRepeat } from "react-native-reanimated"
function App() {
sv.value = withRepeat(withSpring(0), 5)
// ...
}
```
#### Arguments
##### `animation`
The animation object you wish to repeat.
##### `numberOfReps` (Optional)
Specifies how many times the animation should be repeated. The default is `2`.
A non-positive value, such as `0` or `-1`, will cause the animation to repeat indefinitely until it is canceled or removed. For instance, if the component unmounts or `cancelAnimation` is invoked.
##### `reverse` (Optional)
Determines whether the animation should alternate directions with each repetition. The default setting is `false`.
This feature only supports direct animation functions like `withSpring` and does not work with other animation modifiers such as `withSequence`.
##### `callback` (Optional)
A function that executes upon the completion of the animation. If the animation is canceled, the callback receives `false`; otherwise, it receives `true`.
##### `reduceMotion` (Optional)
Controls how the animation responds to the device's reduced motion accessibility setting.
#### Returns
The `withRepeat` function returns an animation object representing the current state of the animation. This can be directly assigned to a shared value or used as a style object returned from `useAnimatedStyle`.
### Remarks
- The callback provided in the fourth argument is automatically workletized and executed on the UI thread.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## useComposedEventHandler
The `useComposedEventHandler` hook allows you to combine multiple event handlers, such as those created with `useAnimatedScrollHandler`, into a single handler.
### Reference Example
```typescript
import Animated, {
useAnimatedScrollHandler,
useComposedEventHandler,
} from 'react-native-reanimated';
function ComposedEventHandlerExample() {
const onScrollHandler1 = useAnimatedScrollHandler({
onScroll(e) {
console.log('Scroll handler 1 onScroll event');
},
});
const onScrollHandler2 = useAnimatedScrollHandler({
onScroll(e) {
console.log('Scroll handler 2 onScroll event');
},
});
const composedHandler = useComposedEventHandler([
onScrollHandler1,
onScrollHandler2,
]);
return (
);
}
```
#### Arguments
- **`handlers`**: An array of event handlers created using the `useEvent` hook. The `useComposedEventHandler` hook updates whenever there are changes in these handlers.
#### Returns
The hook returns a handler object that can be used with any `Animated component`. This handler should be assigned to the corresponding `onEvent` prop (e.g., `onScroll` for scroll-related handlers). For better code clarity, it's recommended to use multiple composed handlers if your aggregated handler manages various events.
### Remarks
- The returned handler combines the functionalities of all provided handlers. This allows multiple handlers to respond to a single event and manage different types of events with one object.
- It functions effectively when used with multiple `Animated components`, triggering event callbacks for each connected component.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## withDelay
`withDelay` is an animation modifier that allows you to initiate an animation after a specified delay period.
### Reference
```typescript
import { withDelay } from "react-native-reanimated"
function App() {
sv.value = withDelay(500, withTiming(0))
// ...
}
```
#### Arguments
- **`delayMs`**: Specifies the duration (in milliseconds) before the animation begins.
- **`delayedAnimation`**: The animation that will be delayed.
- **`reduceMotion`** *(Optional)*: Determines how the animation responds to the device's reduced motion accessibility setting.
#### Returns
The `withDelay` function returns an animation object representing the current state of the animation. This object can either be directly assigned to a shared value or used as a value for a style object returned from `useAnimatedStyle`.
### Example
*(Example content would go here)*
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
***
## useAnimatedSensor
`useAnimatedSensor` allows you to create animations based on device sensor data. It provides access to:
- **Accelerometer**: Measures device acceleration (excluding gravity) along the x, y, and z axes.
- **Gyroscope**: Captures the rotation rate of the device along the x, y, and z axes.
- **Gravity**: Provides the current gravity vector along the x, y, and z axes.
- **Magnetic Field**: Measures the Earth's magnetic field strength and direction in microtesla (μT).
- **Rotation**: Represents the device orientation using Euler angles and a quaternion.
For comprehensive documentation, refer to the Sensors guide on Android Developers and Device Motion in Apple Developer documentation.
### Reference
```typescript
import { useAnimatedSensor, SensorType } from "react-native-reanimated"
function App() {
const gyroscope = useAnimatedSensor(SensorType.GYROSCOPE)
useDerivedValue(() => {
const { x, y, z } = gyroscope.sensor.value
})
}
```
#### Arguments
##### `sensorType`
Specifies the sensor type using a `SensorType` enum:
- `ACCELEROMETER`: Measures device acceleration in m/s².
- `GYROSCOPE`: Captures rotation rate in radians per second.
- `GRAVITY`: Provides gravity vector in m/s².
- `MAGNETIC_FIELD`: Measures magnetic field strength in microtesla (μT).
- `ROTATION`: Represents orientation using Euler angles and a quaternion.
##### `config` (Optional)
|Name|Type|Default|Description|
|-|-|-|-|
|interval|`number \| "auto"`|`"auto"`|Time between sensor readings in milliseconds. `"auto"` matches the device's screen refresh rate.|
|adjustToInterfaceOrientation|`boolean`|`true`|Adjusts measurements to the current interface orientation.|
|iosReferenceFrame|`IOSReferenceFrame`|`IOSReferenceFrame.Auto`|Frame of reference for iOS sensors.|
Available `IOSReferenceFrame` options:
- `xArbitraryZVertical`: Z axis is vertical, X axis arbitrary in horizontal plane.
- `xArbitraryCorrectedZVertical`: Improved rotation accuracy with Z vertical and X arbitrary.
- `XMagneticNorthZVertical`: Z axis vertical, X points to magnetic north.
- `XTrueNorthZVertical`: Z axis vertical, X points to geographic north.
- `Auto`: Defaults based on device capabilities.
#### Returns
`useAnimatedSensor` returns an object:
|Name|Type|Description|
|-|-|-|
|sensor|`SharedValue`|Shared value with sensor measurements.|
|unregister|`() => void`|Stops listening to sensor updates when called.|
|isAvailable|`boolean`|Indicates if the sensor is available for use.|
|config|`SensorConfig`|Contains sensor configuration details.|
The shared value from the **rotation sensor** includes:
- Euler angles: `roll`, `pitch`, `yaw`.
- Quaternion components: `qw`, `qx`, `qy`, `qz`.
- Interface orientation.
Other sensors return measurements on x, y, z axes and interface orientation.
`InterfaceOrientation` enum values:
- `ROTATION_0`: Default rotation on Android, portrait on iOS.
- `ROTATION_90`: 90 degrees on Android, landscape right on iOS.
- `ROTATION_180`: 180 degrees on Android, upside down on iOS.
- `ROTATION_270`: 270 degrees on Android, landscape left on iOS.
### Example
```typescript
export default function App() {
const gravity = useAnimatedSensor(SensorType.GRAVITY);
const animatedStyle = useAnimatedStyle(() => {
return {
transform: [
{ translateX: withSpring(gravity.sensor.value.x * 20) },
{ translateY: withSpring(gravity.sensor.value.y * 20) },
],
};
});
return (
);
}
```
### Remarks
- On iOS, enable location services (`Settings > Privacy > Location Services`) to read sensor data.
- On Web, ensure the device supports sensors and the application is served over HTTPS.
- Most sensors operate at resolutions up to 100Hz.
- Sensor data can be accessed on both UI and JavaScript threads.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|✅|
## dispatchCommand
The `dispatchCommand` function enables the execution of commands directly on a native component from the UI thread.
### Reference
```typescript
import { dispatchCommand } from 'react-native-reanimated';
function App() {
const animatedRef = useAnimatedRef();
const gesture = Gesture.Tap().onStart(() => {
dispatchCommand(animatedRef, 'focus');
});
return (
<>
);
}
```
#### Arguments
- **`animatedRef`**: An animated reference linked to the component you wish to update. This reference must be associated with either an Animated component or a React Native built-in component.
- **`commandName`**: The name of the command to execute, such as `'focus'` or `'scrollToEnd'`.
- **`args` (Optional)**: An array of arguments for the command. Defaults to an empty array if not provided.
### Example
```typescript
const goDown = Gesture.Tap().onStart(() => {
dispatchCommand(tosRef, "scrollToEnd", [true])
dispatchCommand(loginRef, "focus")
})
```
### Remarks
- Commands vary depending on the component. Refer to the relevant React Native documentation for available commands specific to each component.
### Platform Compatibility
|Android|iOS|Web|
|-|-|-|
|✅|✅|❌|
## setNativeProps
The `setNativeProps` function allows for the imperative updating of component properties in React Native. It serves as an escape hatch intended for specific edge cases.
> **Caution:**\
> Prefer using `useAnimatedStyle` and `useAnimatedProps` when animating styles or properties, reserving `setNativeProps` for exceptional situations.
### Reference
```typescript
import { setNativeProps } from 'react-native-reanimated';
function App() {
const animatedRef = useAnimatedRef();
const tap = Gesture.Tap().onEnd(() => {
setNativeProps(animatedRef, { text: '' });
});
return