react-native-text-animations

Smooth, customizable staggered text animations for React Native, built with Reanimated. Includes multiple ready-to-use animated text components with flexible props.

🎬 Animations Preview

| FadeText | RotateText | | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | | | |

| SpringText | WaveText | | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | | |

Installation

npm install react-native-text-animations

Dependencies

npm install react-native-reanimated react-native-worklets

If you’re using Expo SDK 54 or later, these dependencies are preconfigured. Note: Since this library relies on Reanimated v4, enabling the new architecture is mandatory.

Usage

🎨 Available Components

The library exposes five powerful components to bring your text to life:

Pre-built Animation Components

• FadeText - Smooth fade-in/out animations with customizable opacity transitions
• RotateText - Dynamic rotation effects for eye-catching text
• SpringText - Bouncy, spring-based animations with natural motion
• WaveText - Flowing wave effects that ripple through your text

Customizable Component

• AnimatedText (default export) - A fully customizable component for creating your own unique animations with maximum flexibility

📖 Component API

FadeText

Animate text with smooth fade transitions and positional offsets.

Props

| Prop | Type | Default | Description | | -------------- | -------- | ------- | ----------------------------------------------------- | | duration | number | 300 | Animation duration for each segment (in milliseconds) | | delay | number | - | Delay before the animation starts (in milliseconds) | | staggerDelay | number | 50 | Delay between each animated segment (in milliseconds) | | offsetX | number | - | Initial horizontal offset on the X-axis | | offsetY | number | 10 | Initial vertical offset on the Y-axis | | fromOpacity | number | 0 | Starting opacity value (0 to 1) | | toOpacity | number | 1 | Ending opacity value (0 to 1) |

Example

import { FadeText } from 'react-native-text-animations';

<FadeText
  duration={1000}
  delay={200}
  staggerDelay={50}
  offsetY={20}
  fromOpacity={0}
  toOpacity={1}
>
  Hello, World!
</FadeText>;

RotateText

Create dynamic rotation effects with full control over X, Y, and Z axes transformations.

Props

| Prop | Type | Default | Description | | ---------------- | -------- | ------- | ----------------------------------------------------- | | duration | number | 300 | Animation duration for each segment (in milliseconds) | | delay | number | - | Delay before the animation starts (in milliseconds) | | staggerDelay | number | 50 | Delay between each animated segment (in milliseconds) | | offsetX | number | 10 | Initial horizontal offset on the X-axis | | offsetY | number | 10 | Initial vertical offset on the Y-axis | | initialOpacity | number | 0.8 | Starting opacity value (0 to 1) | | rotateXStart | number | - | Initial rotation angle around the X-axis (in degrees) | | rotateXEnd | number | - | Final rotation angle around the X-axis (in degrees) | | rotateYStart | number | 360 | Initial rotation angle around the Y-axis (in degrees) | | rotateYEnd | number | - | Final rotation angle around the Y-axis (in degrees) | | rotateZStart | number | - | Initial rotation angle around the Z-axis (in degrees) | | rotateZEnd | number | - | Final rotation angle around the Z-axis (in degrees) |

Example

import { RotateText } from 'react-native-text-animations';

<RotateText
  duration={1200}
  delay={100}
  staggerDelay={80}
  initialOpacity={0}
  rotateYStart={90}
  rotateYEnd={0}
  offsetX={-20}
>
  Rotating Text!
</RotateText>;

SpringText

Add playful, bouncy spring animations with natural physics-based motion and scaling effects.

Props

| Prop | Type | Default | Description | | ---------------- | ------------ | -------------- | ----------------------------------------------------------------------------------- | | duration | number | 300 | Animation duration for each segment (in milliseconds) | | delay | number | - | Delay before the animation starts (in milliseconds) | | staggerDelay | number | 50 | Delay between each animated segment (in milliseconds) | | offsetX | number | - | Initial horizontal offset on the X-axis | | offsetY | number | -10 | Initial vertical offset on the Y-axis | | scaleFrom | number | 0.5 | Initial scale value (e.g., 0.5 for 50% size) | | scaleTo | number | 1 | Final scale value (e.g., 1 for 100% size) | | initialOpacity | number | 0 | Starting opacity value (0 to 1) | | bounce | BounceType | {x: 2, y: 0.5} | Bounce intensity. Can be a single number or object with separate x and y values |

Types

type BounceType = number | { x?: number; y?: number };

Example

import { SpringText } from 'react-native-text-animations';

<SpringText
  duration={800}
  delay={150}
  staggerDelay={60}
  scaleFrom={0}
  scaleTo={1}
  initialOpacity={0}
  bounce={0.5}
>
  Bouncy Text!
</SpringText>;

WaveText

Create mesmerizing wave effects that flow through your text with smooth, rhythmic motion.

Props

| Prop | Type | Default | Description | | ---------------- | --------- | ------- | ----------------------------------------------------- | | duration | number | 300 | Animation duration for each segment (in milliseconds) | | delay | number | - | Delay before the animation starts (in milliseconds) | | staggerDelay | number | 50 | Delay between each animated segment (in milliseconds) | | amplitude | number | 10 | Height/intensity of the wave effect (in pixels) | | initialOpacity | number | 1 | Starting opacity value (0 to 1) | | infinite | boolean | false | Whether the wave animation should loop continuously |

Example

import { WaveText } from 'react-native-text-animations';

<WaveText duration={1000} staggerDelay={100} amplitude={20} initialOpacity={0}>
  Wave Effect!
</WaveText>;

AnimatedText (Default Export)

The ultimate flexible component that combines all animation capabilities. Create custom animations by composing any combination of fade, rotate, scale, and bounce effects.

Props

| Prop | Type | Required | Description | | -------- | -------------------- | -------- | ---------------------------------------------------- | | config | AnimatedTextConfig | No | Configuration object defining the animation behavior |

AnimatedTextConfig Type

type AnimatedTextConfig = {
  duration?: number;
  delay?: number;
  staggerDelay?: number;
  offsetX?: number;
  offsetY?: number;
  fromOpacity?: number;
  toOpacity?: number;
  rotateFrom?: {
    x?: number;
    y?: number;
    z?: number;
  };
  rotateTo?: {
    x?: number;
    y?: number;
    z?: number;
  };
  scaleFrom?: number;
  scaleTo?: number;
  bounce?: BounceType;
};

type BounceType = number | { x?: number; y?: number };

Config Properties

| Property | Type | Default | Description | | -------------- | ---------------------------------- | ------------- | ----------------------------------------------------- | | duration | number | 300 | Animation duration for each segment (in milliseconds) | | delay | number | - | Delay before the animation starts (in milliseconds) | | staggerDelay | number | 50 | Delay between each animated segment (in milliseconds) | | offsetX | number | - | Initial horizontal offset on the X-axis | | offsetY | number | 10 | Initial vertical offset on the Y-axis | | fromOpacity | number | - | Starting opacity value (0 to 1) | | toOpacity | number | 1 | Ending opacity value (0 to 1) | | rotateFrom | { x:number, y:number, z:number } | - | Initial rotation angles for X, Y, Z axes (in degrees) | | rotateTo | { x:number, y:number, z:number } | - | Final rotation angles for X, Y, Z axes (in degrees) | | scaleFrom | number | 1 | Initial scale value (e.g., 0.5 for 50% size) | | scaleTo | number | 1 | Final scale value (e.g., 1 for 100% size) | | bounce | BounceType | { x: 0,y: 0 } | Bounce intensity (number or object with x/y values) |

Examples

import AnimatedText, { AnimatedTextConfig } from 'react-native-text-animations';

// Inline config
<AnimatedText
  config={{
    duration: 1000,
    staggerDelay: 50,
    fromOpacity: 0,
    toOpacity: 1,
    scaleFrom: 0.8,
    scaleTo: 1,
    offsetY: 20,
  }}
>
  Custom Animation!
</AnimatedText>

// Separate config (recommended for reusability)
const myAnimationConfig: AnimatedTextConfig = {
  duration: 1200,
  delay: 200,
  staggerDelay: 80,
  fromOpacity: 0,
  toOpacity: 1,
  rotateFrom: { y: 90, z: -10 },
  rotateTo: { y: 0, z: 0 },
  scaleFrom: 0.5,
  scaleTo: 1,
  offsetX: -30,
  bounce: { x: 0.3, y: 0.5 },
};

<AnimatedText config={myAnimationConfig}>
  Complex Animation!
</AnimatedText>

// Combining multiple effects
const fadeRotateScale: AnimatedTextConfig = {
  duration: 800,
  staggerDelay: 60,
  fromOpacity: 0,
  toOpacity: 1,
  rotateFrom: { x: 45, y: 45 },
  rotateTo: { x: 0, y: 0 },
  scaleFrom: 0.3,
  scaleTo: 1,
};

<AnimatedText config={fadeRotateScale}>
  Multi-effect Text!
</AnimatedText>

💡 Pro Tips

• Reusability: Export your AnimatedTextConfig objects to reuse across your app
• Composition: Combine multiple animation properties for unique effects
• Performance: Use staggerDelay wisely for smooth sequential animations
• Experimentation: Mix and match properties to discover creative animations

🔧 Common Props

All animation components share these common properties for controlling text content and behavior.

Props

| Prop | Type | Required | Default | Description | | ----------------------- | ---------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- | | text | string | Yes | - | The text content to be animated | | textStyle | StyleProp<TextStyle> | No | - | Style object to customize the appearance of the animated text | | className | string | No | - | Tailwind classes for styling individual letters (requires NativeWind) | | wrapperStyle | StyleProp<ViewStyle> | No | - | Style object for the letter wrapper container | | wrapperClassName | string | No | - | Tailwind classes for the letter wrapper container (requires NativeWind) | | staggerSeparator | string | No | "" | Character(s) used to split text into animated segments. Empty string animates each character individually | | reanimateOnTextChange | boolean | No | false | Whether to restart the animation when the text prop changes |

Note: The className and wrapperClassName props require NativeWind to be properly configured in your project. The wrapper styles help control the layout direction (horizontal/vertical) and positioning of animated letters using flexbox and other layout properties.

Examples

import { FadeText } from 'react-native-text-animations';

// Basic usage with required text prop
<FadeText
  text="Hello World"
  duration={1000}
  fromOpacity={0}
  toOpacity={1}
/>

// With custom text styling
<FadeText
  text="Styled Text"
  textStyle={{
    fontSize: 24,
    fontWeight: 'bold',
    color: '#FF6B6B',
  }}
  duration={800}
  staggerDelay={50}
/>

// Animate words instead of characters
<FadeText
  text="Animate each word separately"
  staggerSeparator=" "
  duration={600}
  staggerDelay={100}
/>

// Reanimate on text change
<FadeText
  text={dynamicText}
  reanimateOnTextChange={true}
  duration={500}
  fromOpacity={0}
  toOpacity={1}
/>

// Animate by custom separator (e.g., sentences)
<SpringText
  text="First sentence.Second sentence.Third sentence"
  staggerSeparator="."
  duration={1000}
  staggerDelay={200}
  scaleFrom={0}
  scaleTo={1}
/>

💡 Understanding staggerSeparator

The staggerSeparator prop controls how text is divided into animated segments:

• "" (default) - Animates each character individually
• " " (space) - Animates each word
• "." (period) - Animates each sentence
• Any custom string - Split by your own delimiter

This gives you fine-grained control over the animation flow!

🐛 Troubleshooting

If you're experiencing issues with the animations, follow these steps:

Animation Not Working?

1. Check Reanimated Version

   • Ensure you have react-native-reanimated v4.1.1 or higher installed
   • Run npm list react-native-reanimated to verify your version

2. Verify Worklets Configuration

   • Make sure react-native-worklets is properly installed
   • Both libraries need to be correctly configured in your project

3. Babel Configuration (Bare React Native Projects)

   • Non-Expo projects require Babel plugin configuration
   • Add the Reanimated plugin to your babel.config.js:

   module.exports = {
     presets: [...],
     plugins: [
       'react-native-reanimated/plugin', // Must be listed last
     ],
   };

• After updating Babel config, clear cache: npx react-native start --reset-cache

Still Having Issues?

If the above steps don't resolve your problem:

• Check existing issues: GitHub Issues
• Report a bug: Open a new issue with:
  • React Native version
  • Expo SDK version (if applicable)
  • Reanimated version
  • Steps to reproduce
  • Error messages or unexpected behavior

We're here to help! 🤝

Contributing

• Development workflow
• Sending a pull request
• Code of conduct

License

MIT

Made with create-react-native-library