Remove ref in render antipattern in animated docs

Reading or writing to a ref in render is a [rule of React violation](https://react.dev/reference/react/useRef). This PR updates the docs for animated to use the `useAnimatedValue` hook instead, which does use a ref under the hood but isolates the rule of React violation to just that hook. This allows users that follow code examples for animated to have their components and hooks be compilable by React Compiler. This hook was added in [0.71](https://github.com/facebook/react-native/blob/main/CHANGELOG.md#:~:text=Introduce%20useAnimatedValue%20hook%20to%20make%20it%20easier%20working%20with%20Animated.Values%20in%20function%20components.%20(e22217fe8b%20by%20%40fabriziocucci)) so I'm also updating versioned docs from 0.71 onwards.
facebook · Oct 30, 2024 · f6728c4 · f6728c4
1 parent e20b097
commit f6728c4
Show file tree

Hide file tree

Showing 40 changed files with 198 additions and 152 deletions.
diff --git a/docs/animated.md b/docs/animated.md
@@ -13,14 +13,21 @@ The core workflow for creating an animation is to create an `Animated.Value`, ho
 
 The following example contains a `View` which will fade in and fade out based on the animated value `fadeAnim`
 
-```SnackPlayer name=Animated%20Example
-import React, {useRef} from 'react';
-import {Animated, Text, View, StyleSheet, Button} from 'react-native';
+```SnackPlayer name=Animated%20Example&supportedPlatforms=ios,android
+import React from 'react';
 import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';
+import {
+  Animated,
+  Text,
+  View,
+  StyleSheet,
+  Button,
+  useAnimatedValue,
+} from 'react-native';
 
 const App = () => {
   // fadeAnim will be used as the value for opacity. Initial Value: 0
-  const fadeAnim = useRef(new Animated.Value(0)).current;
+  const fadeAnim = useAnimatedValue(0);
 
   const fadeIn = () => {
     // Will change fadeAnim value to 1 in 5 seconds
@@ -495,7 +502,7 @@ Stops any running animation and resets the value to its original.
 
 ### `Value`
 
-Standard value class for driving animations. Typically initialized with `new Animated.Value(0);`
+Standard value class for driving animations. Typically initialized with `useAnimatedValue(0);` or `new Animated.Value(0);` in class components.
 
 You can read more about `Animated.Value` API on the separate [page](animatedvalue).
 

diff --git a/docs/animatedvalue.md b/docs/animatedvalue.md
@@ -5,7 +5,7 @@ title: Animated.Value
 
 Standard value for driving animations. One `Animated.Value` can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling `setValue`) will stop any previous ones.
 
-Typically initialized with `new Animated.Value(0);`
+Typically initialized with `useAnimatedValue(0);` or `new Animated.Value(0);` in class components.
 
 ---
 

diff --git a/docs/animations.md b/docs/animations.md
@@ -21,11 +21,11 @@ For example, a container view that fades in when it is mounted may look like thi
 <TabItem value="javascript">
 
 ```SnackPlayer ext=js
-import React, {useRef, useEffect} from 'react';
-import {Animated, Text, View} from 'react-native';
+import React, {useEffect} from 'react';
+import {Animated, Text, View, useAnimatedValue} from 'react-native';
 
 const FadeInView = props => {
-  const fadeAnim = useRef(new Animated.Value(0)).current; // Initial value for opacity: 0
+  const fadeAnim = useAnimatedValue(0); // Initial value for opacity: 0
 
   useEffect(() => {
     Animated.timing(fadeAnim, {
@@ -74,15 +74,15 @@ export default () => {
 <TabItem value="typescript">
 
 ```SnackPlayer ext=tsx
-import React, {useRef, useEffect} from 'react';
-import {Animated, Text, View} from 'react-native';
+import React, {useEffect} from 'react';
+import {Animated, Text, View, useAnimatedValue} from 'react-native';
 import type {PropsWithChildren} from 'react';
 import type {ViewStyle} from 'react-native';
 
 type FadeInViewProps = PropsWithChildren<{style: ViewStyle}>;
 
 const FadeInView: React.FC<FadeInViewProps> = props => {
-  const fadeAnim = useRef(new Animated.Value(0)).current; // Initial value for opacity: 0
+  const fadeAnim = useAnimatedValue(0); // Initial value for opacity: 0
 
   useEffect(() => {
     Animated.timing(fadeAnim, {
@@ -311,7 +311,7 @@ The following example implements a horizontal scrolling carousel where the scrol
 #### ScrollView with Animated Event Example
 
 ```SnackPlayer name=Animated&supportedPlatforms=ios,android
-import React, {useRef} from 'react';
+import React from 'react';
 import {
   ScrollView,
   Text,
@@ -320,6 +320,7 @@ import {
   ImageBackground,
   Animated,
   useWindowDimensions,
+  useAnimatedValue,
 } from 'react-native';
 import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';
 
@@ -328,7 +329,7 @@ const images = new Array(6).fill(
 );
 
 const App = () => {
-  const scrollX = useRef(new Animated.Value(0)).current;
+  const scrollX = useAnimatedValue(0);
 
   const {width: windowWidth} = useWindowDimensions();
 

diff --git a/docs/easing.md b/docs/easing.md
@@ -48,7 +48,7 @@ The following helpers are used to modify other easing functions.
 <Tabs groupId="language" queryString defaultValue={constants.defaultSnackLanguage} values={constants.snackLanguages}>
 <TabItem value="javascript">
 
-```SnackPlayer name=Easing%20Demo&ext=js
+```SnackPlayer name=Easing%20Demo&ext=js&supportedPlatforms=ios,android
 import React from 'react';
 import {
   Animated,
@@ -59,11 +59,12 @@ import {
   Text,
   TouchableOpacity,
   View,
+  useAnimatedValue,
 } from 'react-native';
 import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';
 
 const App = () => {
-  let opacity = new Animated.Value(0);
+  const opacity = useAnimatedValue(0);
 
   const animate = easing => {
     opacity.setValue(0);
@@ -219,12 +220,13 @@ import {
   Text,
   TouchableOpacity,
   View,
+  useAnimatedValue,
   type EasingFunction,
 } from 'react-native';
 import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';
 
 const App = () => {
-  let opacity = new Animated.Value(0);
+  const opacity = useAnimatedValue(0);
 
   const animate = (easing: EasingFunction) => {
     opacity.setValue(0);

diff --git a/docs/interactionmanager.md b/docs/interactionmanager.md
@@ -47,14 +47,15 @@ By default, queued tasks are executed together in a loop in one `setImmediate` b
 <TabItem value="javascript">
 
 ```SnackPlayer name=InteractionManager%20Function%20Component%20Basic%20Example&supportedPlatforms=ios,android&ext=js
-import React, {useState, useEffect} from 'react';
+import React, {useEffect} from 'react';
 import {
   Alert,
   Animated,
   InteractionManager,
   Platform,
   StyleSheet,
   Text,
+  useAnimatedValue,
 } from 'react-native';
 import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';
 
@@ -66,7 +67,7 @@ const instructions = Platform.select({
 });
 
 const useFadeIn = (duration = 5000) => {
-  const [opacity] = useState(new Animated.Value(0));
+  const opacity = useAnimatedValue(0);
 
   // Running the animation when the component is mounted
   useEffect(() => {
@@ -128,14 +129,15 @@ export default App;
 <TabItem value="typescript">
 
 ```SnackPlayer name=InteractionManager%20Function%20Component%20Basic%20Example&supportedPlatforms=ios,android&ext=tsx
-import React, {useState, useEffect} from 'react';
+import React, {useEffect} from 'react';
 import {
   Alert,
   Animated,
   InteractionManager,
   Platform,
   StyleSheet,
   Text,
+  useAnimatedValue,
 } from 'react-native';
 import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';
 
@@ -147,7 +149,7 @@ const instructions = Platform.select({
 });
 
 const useFadeIn = (duration = 5000) => {
-  const [opacity] = useState(new Animated.Value(0));
+  const opacity = useAnimatedValue(0);
 
   // Running the animation when the component is mounted
   useEffect(() => {

diff --git a/docs/transforms.md b/docs/transforms.md
@@ -211,13 +211,19 @@ The `transformOrigin` property sets the origin for a view's transformations. The
 
 # Example
 
-```SnackPlayer name=TransformOrigin%20Example
-import React, {useRef, useEffect} from 'react';
-import {Animated, View, StyleSheet, Easing} from 'react-native';
+```SnackPlayer name=TransformOrigin%20Example&supportedPlatforms=ios,android
+import React, {useEffect} from 'react';
+import {
+  Animated,
+  View,
+  StyleSheet,
+  Easing,
+  useAnimatedValue,
+} from 'react-native';
 import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context';
 
 const App = () => {
-  const rotateAnim = useRef(new Animated.Value(0)).current;
+  const rotateAnim = useAnimatedValue(0);
 
   useEffect(() => {
     Animated.loop(

diff --git a/website/versioned_docs/version-0.70/easing.md b/website/versioned_docs/version-0.70/easing.md
@@ -43,7 +43,7 @@ The following helpers are used to modify other easing functions.
 
 ## Example
 
-```SnackPlayer name=Easing%20Demo
+```SnackPlayer name=Easing%20Demo&supportedPlatforms=ios,android
 import React from "react";
 import { Animated, Easing, SectionList, StatusBar, StyleSheet, Text, TouchableOpacity, View } from "react-native";
 

diff --git a/website/versioned_docs/version-0.70/interactionmanager.md b/website/versioned_docs/version-0.70/interactionmanager.md
@@ -42,7 +42,7 @@ By default, queued tasks are executed together in a loop in one `setImmediate` b
 ### Basic
 
 ```SnackPlayer name=InteractionManager%20Function%20Component%20Basic%20Example&supportedPlatforms=ios,android
-import React, { useState, useEffect } from "react";
+import React, { useEffect } from "react";
 import {
   Alert,
   Animated,
@@ -51,6 +51,7 @@ import {
   StyleSheet,
   Text,
   View,
+  useAnimatedValue,
 } from "react-native";
 
 const instructions = Platform.select({
@@ -63,7 +64,7 @@ const instructions = Platform.select({
 const useMount = func => useEffect(() => func(), []);
 
 const useFadeIn = (duration = 5000) => {
-  const [opacity] = useState(new Animated.Value(0));
+  const opacity = useAnimatedValue(0);
 
   // Running the animation when the component is mounted
   useMount(() => {

diff --git a/website/versioned_docs/version-0.71/animated.md b/website/versioned_docs/version-0.71/animated.md
@@ -29,20 +29,21 @@ The following example contains a `View` which will fade in and fade out based on
 <Tabs groupId="syntax" queryString defaultValue={constants.defaultSyntax} values={constants.syntax}>
 <TabItem value="functional">
 
-```SnackPlayer name=Animated
-import React, {useRef} from 'react';
+```SnackPlayer name=Animate&supportedPlatforms=ios,android
+import React from 'react';
 import {
   Animated,
   Text,
   View,
   StyleSheet,
   Button,
   SafeAreaView,
+  useAnimatedValue,
 } from 'react-native';
 
 const App = () => {
   // fadeAnim will be used as the value for opacity. Initial Value: 0
-  const fadeAnim = useRef(new Animated.Value(0)).current;
+  const fadeAnim = useAnimatedValue(0);
 
   const fadeIn = () => {
     // Will change fadeAnim value to 1 in 5 seconds
@@ -601,7 +602,7 @@ Stops any running animation and resets the value to its original.
 
 ### `Value`
 
-Standard value class for driving animations. Typically initialized with `new Animated.Value(0);`
+Standard value class for driving animations. Typically initialized with `useAnimatedValue(0)` or `new Animated.Value(0);` in class components.
 
 You can read more about `Animated.Value` API on the separate [page](animatedvalue).
 

diff --git a/website/versioned_docs/version-0.71/animatedvalue.md b/website/versioned_docs/version-0.71/animatedvalue.md
@@ -5,7 +5,7 @@ title: Animated.Value
 
 Standard value for driving animations. One `Animated.Value` can drive multiple properties in a synchronized fashion, but can only be driven by one mechanism at a time. Using a new mechanism (e.g. starting a new animation, or calling `setValue`) will stop any previous ones.
 
-Typically initialized with `new Animated.Value(0);`
+Typically initialized with `useAnimatedValue(0) or `new Animated.Value(0);` in class components.
 
 ---
 

diff --git a/website/versioned_docs/version-0.71/animations.md b/website/versioned_docs/version-0.71/animations.md
@@ -21,11 +21,11 @@ For example, a container view that fades in when it is mounted may look like thi
 <TabItem value="javascript">
 
 ```SnackPlayer ext=js
-import React, {useRef, useEffect} from 'react';
+import React, {useEffect, useAnimatedValue} from 'react';
 import {Animated, Text, View} from 'react-native';
 
 const FadeInView = props => {
-  const fadeAnim = useRef(new Animated.Value(0)).current; // Initial value for opacity: 0
+  const fadeAnim = useAnimatedValue(0); // Initial value for opacity: 0
 
   useEffect(() => {
     Animated.timing(fadeAnim, {
@@ -74,15 +74,15 @@ export default () => {
 <TabItem value="typescript">
 
 ```SnackPlayer ext=tsx
-import React, {useRef, useEffect} from 'react';
-import {Animated, Text, View} from 'react-native';
+import React, {useEffect} from 'react';
+import {Animated, Text, View, useAnimatedValue} from 'react-native';
 import type {PropsWithChildren} from 'react';
 import type {ViewStyle} from 'react-native';
 
 type FadeInViewProps = PropsWithChildren<{style: ViewStyle}>;
 
 const FadeInView: React.FC<FadeInViewProps> = props => {
-  const fadeAnim = useRef(new Animated.Value(0)).current; // Initial value for opacity: 0
+  const fadeAnim = useAnimatedValue(0); // Initial value for opacity: 0
 
   useEffect(() => {
     Animated.timing(fadeAnim, {
@@ -314,7 +314,7 @@ The following example implements a horizontal scrolling carousel where the scrol
 <TabItem value="functional">
 
 ```SnackPlayer name=Animated&supportedPlatforms=ios,android
-import React, {useRef} from 'react';
+import React from 'react';
 import {
   SafeAreaView,
   ScrollView,
@@ -324,14 +324,15 @@ import {
   ImageBackground,
   Animated,
   useWindowDimensions,
+  useAnimatedValue,
 } from 'react-native';
 
 const images = new Array(6).fill(
   'https://images.unsplash.com/photo-1556740749-887f6717d7e4',
 );
 
 const App = () => {
-  const scrollX = useRef(new Animated.Value(0)).current;
+  const scrollX = useAnimatedValue(0);
 
   const {width: windowWidth} = useWindowDimensions();
 

diff --git a/website/versioned_docs/version-0.71/easing.md b/website/versioned_docs/version-0.71/easing.md
@@ -59,10 +59,11 @@ import {
   Text,
   TouchableOpacity,
   View,
+  useAnimatedValue,
 } from 'react-native';
 
 const App = () => {
-  let opacity = new Animated.Value(0);
+  let opacity = useAnimatedValue(0);
 
   const animate = easing => {
     opacity.setValue(0);
@@ -203,7 +204,7 @@ export default App;
 </TabItem>
 <TabItem value="typescript">
 
-```SnackPlayer name=Easing%20Demo&ext=tsx
+```SnackPlayer name=Easing%20Demo&ext=tsx&supportedPlatforms=ios,android
 import React from 'react';
 import {
   Animated,
@@ -214,11 +215,12 @@ import {
   Text,
   TouchableOpacity,
   View,
+  useAnimatedValue,
 } from 'react-native';
 import type {EasingFunction} from 'react-native';
 
 const App = () => {
-  let opacity = new Animated.Value(0);
+  let opacity = useAnimatedValue(0);
 
   const animate = (easing: EasingFunction) => {
     opacity.setValue(0);