React Native Reanimated Text

A highly customizable animated text component for React Native using Reanimated v3. Create beautiful letter-by-letter animations with spring physics, stagger effects, and extensive configuration options.

Features

• 🎨 Highly Customizable - Control every aspect of the animation
• ⚡ Performance Optimized - Built with React Native Reanimated v3
• 🔤 Letter-by-Letter Animation - Individual letter control and timing
• 🎪 Multiple Animation Types - Slide, flip, scale, fade, and more
• 📱 TypeScript Support - Full type safety and IntelliSense
• 🎯 Stagger Effects - Beautiful sequential animations
• 🔄 Direction Control - Up, down, random, or auto-detection
• ⏱️ Flexible Timing - Custom delays, springs, and triggers
• 🎭 Animation Presets - Pre-built configurations for common use cases

Installation

npm install react-native-text-motion
# or
yarn add react-native-text-motion

Prerequisites

This library requires React Native Reanimated v3:

npm install react-native-reanimated
# Follow the installation guide at https://docs.swmansion.com/react-native-reanimated/

Basic Usage

import React, { useState } from 'react';
import { View, Button } from 'react-native';
import ReanimatedText from 'react-native-text-motion';

const App = () => {
  const [counter, setCounter] = useState(0);

  return (
    <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
      <ReanimatedText
        value={counter}
        style={{
          fontSize: 24,
          fontWeight: 'bold',
          color: '#333',
        }}
      />
      <Button
        title="Increment"
        onPress={() => setCounter(prev => prev + 1)}
      />
    </View>
  );
};

Advanced Examples

Flip Animation with Custom Spring

<ReanimatedText
  value="Hello World"
  preset="flip"
  style={{
    fontSize: 32,
    fontWeight: '600',
    color: '#4A90E2',
  }}
/>

Stagger Animation with Bounce Effect

<ReanimatedText
  value={text}
  preset="bounce"
  style={{
    fontSize: 28,
    letterSpacing: 2,
  }}
/>

Custom Animation Configuration

<ReanimatedText
  value={text}
  preset={{
    direction: 'up',
    axis: 'vertical',
    stagger: 50,
    spring: 'bouncy',
    fade: true,
    scale: true,
    delay: 100,
  }}
  style={{
    fontSize: 24,
    color: '#FF6B6B',
  }}
/>

Manual Trigger

const textRef = useRef<ReanimatedTextRef>(null);

<ReanimatedText
  ref={textRef}
  value="Trigger Me"
  trigger="manual"
  animateOnMount={false}
/>

// Trigger animation programmatically
textRef.current?.trigger();

Advanced Configuration with Exit Animations

<ReanimatedText
  value={text}
  preset="default"
  advanced={{
    translateDistance: 50,
    exitAnimation: true,
    layoutTransition: true,
    customSpring: { damping: 15, stiffness: 200 },
  }}
  style={{
    fontSize: 20,
    color: '#4ECDC4',
  }}
/>

API Reference

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | value | string \| number | - | The text content to animate | | preset | AnimationPreset \| 'default' \| 'flip' \| 'fade' \| 'bounce' | 'default' | Animation preset or custom configuration | | trigger | 'auto' \| 'manual' | 'auto' | How animations are triggered | | animateOnMount | boolean | true | Animate when component mounts | | style | TextStyle | {} | Style applied to each letter | | containerStyle | ViewStyle | {} | Style for the container view | | letterSpacing | number | 0 | Spacing between letters | | vertical | boolean | false | Arrange letters vertically | | advanced | AdvancedConfig | {} | Advanced animation options | | onAnimationStart | () => void | - | Callback when animation starts | | onAnimationComplete | () => void | - | Callback when animation completes |

AnimationPreset Interface

interface AnimationPreset {
  direction?: 'up' | 'down' | 'random' | 'auto';
  axis?: 'vertical' | 'horizontal';
  stagger?: number | boolean;
  spring?: WithSpringConfig | 'default' | 'bouncy' | 'stiff';
  fade?: boolean;
  scale?: boolean | number;
  flip?: boolean;
  delay?: number | 'random';
  duration?: number;
}

Advanced Configuration

interface AdvancedConfig {
  translateDistance?: number;
  exitAnimation?: boolean;
  layoutTransition?: boolean | BaseAnimationBuilder;
  customSpring?: WithSpringConfig;
  customExitSpring?: WithSpringConfig;
}

Built-in Presets

Default

{
  direction: 'auto',
  axis: 'vertical',
  stagger: false,
  spring: 'default',
  fade: true,
}

Flip

{
  direction: 'auto',
  axis: 'vertical',
  flip: true,
  fade: true,
  delay: 250,
  spring: 'bouncy',
}

Fade

{
  direction: 'auto',
  axis: 'vertical',
  fade: true,
  stagger: false,
  spring: 'default',
}

Bounce

{
  direction: 'up',
  axis: 'vertical',
  stagger: true,
  spring: 'bouncy',
  fade: true,
  scale: true,
}

Spring Presets

const SPRING_PRESETS = {
  default: { damping: 20, stiffness: 300 },
  bouncy: { damping: 10, stiffness: 200, mass: 0.8 },
  stiff: { damping: 30, stiffness: 400 },
};

Animation Types

Slide Animation (Default)

Letters slide in from top or bottom with customizable translation distance.

Flip Animation

Letters rotate around X-axis creating a flip effect.

Scale Animation

Letters scale in/out during transitions.

Opacity Animation

Letters fade in/out with customizable opacity ranges.

Stagger Effects

Sequential animation of letters with customizable delays.

Exit Animations

Previous letters animate out when text changes (requires exitAnimation: true).

Performance Considerations

• The component uses memo() to prevent unnecessary re-renders
• Animations run on the UI thread via Reanimated v3
• Each letter is individually optimized with useAnimatedStyle
• Layout animations are configurable and can be disabled if not needed
• Automatic cleanup of completed animations

Troubleshooting

Common Issues

1. Animations not working: Ensure React Native Reanimated v3 is properly installed and configured
2. TypeScript errors: Make sure you're using TypeScript 4.0+ and have proper type definitions
3. Performance issues: Consider disabling layout animations or reducing stagger delays for large texts
4. First animation not triggering: The component now properly handles first value changes

Debug Mode

Enable debug logging by setting the __DEV__ flag:

// Add this for debugging (development only)
if (__DEV__) {
  console.log('ReanimatedText Debug Info');
}

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © Mikhail Ozolins