0
# Configuration and Utilities
1

2
Configuration functions, feature flags, property adapters, and utility functions for customizing and extending React Native Reanimated functionality.
3

4
## Capabilities
5

6
### Configuration Helpers
7

8
Functions for configuring Reanimated behavior and extending component properties.
9

10
```typescript { .api }
11
/**
12
 * Adds properties to the whitelist for native props processing
13
 * @param props - Array of property names to whitelist
14
 */
15
function addWhitelistedNativeProps(props: string[]): void;
16

17
/**
18
 * Adds properties to the whitelist for UI props processing
19
 * @param props - Array of property names to whitelist
20
 */
21
function addWhitelistedUIProps(props: string[]): void;
22

23
/**
24
 * Configures the Reanimated logger settings
25
 * @param config - Logger configuration options
26
 */
27
function configureReanimatedLogger(config: LoggerConfig): void;
28

29
interface LoggerConfig {
30
  /** Severity level for logging */
31
  level?: 'debug' | 'info' | 'warn' | 'error';
32
  /** Whether to enable strict mode logging */
33
  strict?: boolean;
34
}
35
```
36

37
**Usage Examples:**
38

39
```typescript
40
import { 
41
  addWhitelistedNativeProps, 
42
  addWhitelistedUIProps,
43
  configureReanimatedLogger 
44
} from "react-native-reanimated";
45

46
// Whitelist custom properties for native processing
47
addWhitelistedNativeProps(['customProperty', 'myNativeProp']);
48

49
// Whitelist properties for UI thread processing
50
addWhitelistedUIProps(['animatedValue', 'customAnimatedProp']);
51

52
// Configure logger
53
configureReanimatedLogger({
54
  level: 'warn',
55
  strict: true,
56
});
57
```
58

59
### Feature Flags
60

61
System for managing experimental features and runtime capabilities.
62

63
```typescript { .api }
64
/**
65
 * Gets a static feature flag value
66
 * @param flag - Feature flag name
67
 * @returns Feature flag value
68
 */
69
function getStaticFeatureFlag(flag: string): boolean | undefined;
70

71
/**
72
 * Sets a dynamic feature flag value
73
 * @param flag - Feature flag name
74
 * @param value - Feature flag value
75
 */
76
function setDynamicFeatureFlag(flag: string, value: boolean): void;
77
```
78

79
**Usage Examples:**
80

81
```typescript
82
import { getStaticFeatureFlag, setDynamicFeatureFlag } from "react-native-reanimated";
83

84
// Check if a feature is enabled
85
const isNewAnimationEngineEnabled = getStaticFeatureFlag('NEW_ANIMATION_ENGINE');
86

87
if (isNewAnimationEngineEnabled) {
88
  // Use new animation features
89
  console.log('Using new animation engine');
90
}
91

92
// Enable experimental features
93
setDynamicFeatureFlag('EXPERIMENTAL_TRANSFORMS', true);
94
setDynamicFeatureFlag('BETA_LAYOUT_ANIMATIONS', false);
95

96
// Feature-gated functionality
97
const MyComponent = () => {
98
  const useBetaFeatures = getStaticFeatureFlag('BETA_FEATURES');
99
  
100
  const animatedStyle = useAnimatedStyle(() => {
101
    if (useBetaFeatures) {
102
      return { 
103
        transform: [{ experimental: 'enabled' }] 
104
      };
105
    }
106
    return { 
107
      transform: [{ scale: 1 }] 
108
    };
109
  });
110

111
  return <Animated.View style={animatedStyle} />;
112
};
113
```
114

115
### Property Adapters
116

117
Functions for creating custom property adaptation logic.
118

119
```typescript { .api }
120
/**
121
 * Creates an animated property adapter for custom prop handling
122
 * @param adapter - Adapter function for property transformation
123
 * @returns Property adapter for use with animated components
124
 */
125
function createAnimatedPropAdapter<T>(
126
  adapter: (props: T) => T
127
): AnimatedPropAdapter<T>;
128

129
type AnimatedPropAdapter<T> = (props: T) => T;
130
```
131

132
**Usage Examples:**
133

134
```typescript
135
import { createAnimatedPropAdapter, useAnimatedProps } from "react-native-reanimated";
136

137
// Create a custom prop adapter
138
const colorAdapter = createAnimatedPropAdapter((props) => {
139
  // Transform color values for platform compatibility
140
  if (props.color && typeof props.color === 'string') {
141
    return {
142
      ...props,
143
      color: Platform.OS === 'android' ? props.color.toUpperCase() : props.color,
144
    };
145
  }
146
  return props;
147
});
148

149
// Custom component with adapter
150
const CustomAnimatedComponent = () => {
151
  const color = useSharedValue('red');
152
  
153
  const animatedProps = useAnimatedProps(() => ({
154
    color: color.value,
155
    customProp: `animated-${color.value}`,
156
  }), [], colorAdapter);
157

158
  return <Animated.View animatedProps={animatedProps} />;
159
};
160

161
// Multiple adapters for complex transformations
162
const multiAdapter = createAnimatedPropAdapter((props) => {
163
  // Apply multiple transformations
164
  let transformedProps = { ...props };
165
  
166
  // Normalize numeric values
167
  if (typeof transformedProps.opacity === 'string') {
168
    transformedProps.opacity = parseFloat(transformedProps.opacity);
169
  }
170
  
171
  // Apply platform-specific adjustments
172
  if (Platform.OS === 'ios' && transformedProps.shadowRadius) {
173
    transformedProps.shadowRadius *= 1.5; // iOS needs larger shadow radius
174
  }
175
  
176
  return transformedProps;
177
});
178
```
179

180
### Version and Compatibility
181

182
Functions for checking Reanimated version and compatibility.
183

184
```typescript { .api }
185
/**
186
 * Gets the current Reanimated JavaScript version
187
 */
188
const reanimatedVersion: string;
189

190
/**
191
 * Checks if the current version is Reanimated 3 or higher
192
 * @returns True if running Reanimated 3+
193
 */
194
function isReanimated3(): boolean;
195

196
/**
197
 * Checks if Reanimated is properly configured
198
 * @returns True if Reanimated is configured correctly
199
 */
200
function isConfigured(): boolean;
201
```
202

203
**Usage Examples:**
204

205
```typescript
206
import { reanimatedVersion, isReanimated3, isConfigured } from "react-native-reanimated";
207

208
// Version checks
209
console.log('Reanimated version:', reanimatedVersion);
210

211
if (isReanimated3()) {
212
  console.log('Using Reanimated 3 features');
213
  // Use modern APIs
214
} else {
215
  console.log('Using legacy Reanimated APIs');
216
  // Fallback to older APIs
217
}
218

219
// Configuration validation
220
if (!isConfigured()) {
221
  console.error('Reanimated is not properly configured');
222
  throw new Error('Please check your Reanimated installation');
223
}
224

225
// Conditional feature usage
226
const MyComponent = () => {
227
  const canUseAdvancedFeatures = isReanimated3() && isConfigured();
228
  
229
  const animatedStyle = useAnimatedStyle(() => {
230
    if (canUseAdvancedFeatures) {
231
      return {
232
        transform: [{ perspective: 1000 }, { rotateX: '45deg' }],
233
      };
234
    }
235
    return {
236
      transform: [{ scale: 1.1 }],
237
    };
238
  });
239

240
  return <Animated.View style={animatedStyle} />;
241
};
242
```
243

244
### Plugin Utilities
245

246
Functions for working with the Reanimated Babel plugin and development warnings.
247

248
```typescript { .api }
249
/**
250
 * Gets a warning about improper shared value usage in styles
251
 * @param usageInfo - Information about the improper usage
252
 * @returns Warning message
253
 */
254
function getUseOfValueInStyleWarning(usageInfo: any): string;
255
```
256

257
**Usage Examples:**
258

259
```typescript
260
import { getUseOfValueInStyleWarning } from "react-native-reanimated";
261

262
// Development helper for plugin warnings
263
const validateStyleUsage = (styleObject: any) => {
264
  if (__DEV__) {
265
    // Check for improper shared value usage
266
    const warning = getUseOfValueInStyleWarning(styleObject);
267
    if (warning) {
268
      console.warn(warning);
269
    }
270
  }
271
};
272

273
// Usage in component
274
const MyComponent = () => {
275
  const scale = useSharedValue(1);
276
  
277
  // This would trigger a warning in development
278
  const incorrectStyle = {
279
    transform: [{ scale: scale }], // Should be scale.value
280
  };
281
  
282
  if (__DEV__) {
283
    validateStyleUsage(incorrectStyle);
284
  }
285
  
286
  // Correct usage
287
  const animatedStyle = useAnimatedStyle(() => ({
288
    transform: [{ scale: scale.value }],
289
  }));
290

291
  return <Animated.View style={animatedStyle} />;
292
};
293
```
294

295
## Types
296

297
### Configuration Types
298

299
```typescript { .api }
300
enum ReanimatedLogLevel {
301
  debug = 0,
302
  info = 1,
303
  warn = 2,
304
  error = 3,
305
}
306

307
interface LoggerConfig {
308
  level?: 'debug' | 'info' | 'warn' | 'error';
309
  strict?: boolean;
310
}
311
```
312

313
### Feature Flag Types
314

315
```typescript { .api }
316
type FeatureFlagName = string;
317
type FeatureFlagValue = boolean | undefined;
318

319
interface FeatureFlags {
320
  [key: string]: FeatureFlagValue;
321
}
322
```
323

324
### Adapter Types
325

326
```typescript { .api }
327
type AnimatedPropAdapter<T> = (props: T) => T;
328

329
interface AnimatedPropsAdapterWorklet<T = Record<string, unknown>> {
330
  (props: T): void;
331
}
332

333
type AnimatedPropsAdapterFunction<T = Record<string, unknown>> = 
334
  (props: T) => void;
335
```