@erosnicolau/animated-text

Advanced React animated text component with comprehensive animation effects and performance optimization.

Features

• 🎨 5 Animation Types - Block, phrase, word, typewriter, and word-typewriter animations
• 🚀 Performance Optimized - FPS monitoring with automatic degradation
• 🔧 Highly Configurable - Extensive customization options for timing, effects, and styling
• 📱 Responsive - Automatic font scaling and mobile-optimized animations
• ♿ Accessible - Respects prefers-reduced-motion with graceful fallbacks
• 🎯 TypeScript - Full type safety with comprehensive interfaces
• 🌐 i18n Ready - Built for multilingual applications with phrase-based styling
• 🎬 Group Coordination - Synchronize multiple animated text elements

Installation

npm install @erosnicolau/animated-text

Quick Start

import AnimatedText from '@erosnicolau/animated-text'

function MyComponent() {
  return <AnimatedText content="Hello, World!" animation="word" wordEffect={['fadeIn', 'slide-up']} />
}

Animation Types

1. Block Animation

Animates the entire text block as one unit.

<AnimatedText
  content="Welcome to our website"
  animation="block"
  blockEffect={['fadeIn', 'slide-up']}
  blockDuration={800}
/>

2. Phrase Animation

Animates phrases separated by "|" character with individual styling.

<AnimatedText
  content="First phrase | Second phrase | Third phrase"
  animation="phrases"
  phraseStyles={[
    { phrase: 1, effect: ['fadeIn', 'slide-up'], className: 'text-blue-600' },
    { phrase: 2, effect: ['fadeIn', 'slide-up'], delayBefore: 300, className: 'text-green-600' },
    { phrase: 3, effect: ['fadeIn', 'slide-up'], delayBefore: 600, className: 'text-purple-600' }
  ]}
/>

3. Word Animation

Animates each word sequentially.

<AnimatedText
  content="Each word appears individually"
  animation="word"
  wordEffect={['fadeIn', 'scale']}
  wordSpacing={200}
/>

4. Typewriter Animation

Animates each letter individually for a classic typewriter effect.

<AnimatedText
  content="Letter by letter animation"
  animation="typewriter"
  typewriterEffect={['fadeIn']}
  typewriterDelay={50}
/>

5. Word-Typewriter Animation

Hybrid animation: letters appear individually with longer pauses between words for natural reading flow.

<AnimatedText
  content="Natural reading flow with pauses"
  animation="word-typewriter"
  wordTypewriterEffect={['fadeIn']}
  wordTypewriterLetterDelay={40}
  wordTypewriterWordDelay={300}
/>

Effects System

The component supports composable effects that can be combined for sophisticated animations:

Simple Effects

• Opacity: fade, fadeIn, fadeOut
• Movement: slide-up, slide-down, slide-left, slide-right
• Scale: scale, scaleX, scaleY
• Rotation: rotate, rotateX, rotateY
• Filters: blur, brightness, contrast

Advanced Object Effects

For precise control, use object notation with custom values:

<AnimatedText
  content="Advanced effects"
  animation="block"
  blockEffect={[
    'fadeIn',
    { type: 'slide', x: 0, y: -30 },
    { type: 'scale', from: 0.5, to: 1 },
    { type: 'rotate', from: 15, to: 0 },
    { type: 'fontSize', from: '12px', to: '48px' },
    { type: 'letterSpacing', from: '8px', to: '2px' },
    { type: 'textShadow', from: 'none', to: '0 0 20px #8b5cf6' },
    { type: 'color', from: '#8b5cf6', to: '#1e40af' }
  ]}
  blockDuration={3000}
/>

Typography Effects

• Font: fontSize, fontWeight, letterSpacing, lineHeight
• Color: color, textShadow
• Spacing: margin, padding, width, height

Visual Effects

• Borders: borderColor, borderWidth, borderRadius
• Shadows: textShadow, boxShadow
• Background: backgroundColor, backdropFilter

Effect Categories by Complexity

Basic (String Effects)

wordEffect={['fadeIn', 'slide-up', 'scale']}

Advanced (Object Effects)

blockEffect={[
  'fadeIn',
  { type: 'fontSize', from: '16px', to: '32px' },
  { type: 'color', from: '#000', to: '#ff6b6b' }
]}

Ultimate (8+ Effect Combinations)

blockEffect={[
  'fadeIn',
  { type: 'slide', x: 0, y: -30 },
  { type: 'scale', from: 0.5, to: 1 },
  { type: 'rotate', from: 15, to: 0 },
  { type: 'fontSize', from: '12px', to: '48px' },
  { type: 'letterSpacing', from: '8px', to: '2px' },
  { type: 'textShadow', from: 'none', to: '0 0 20px #8b5cf6' },
  { type: 'color', from: '#8b5cf6', to: '#1e40af' }
]}

Performance Features

FPS Monitoring

Automatic performance monitoring with graceful degradation:

import { getFPSMetrics, updateFPSThreshold } from '@erosnicolau/animated-text'

// Monitor performance
const metrics = getFPSMetrics()
console.log(`Current FPS: ${metrics.currentFPS}`)

// Adjust performance threshold
updateFPSThreshold(30) // Switch to simplified animations below 30 FPS

Virtualization

Features intersection observer-based virtualization for performance optimization with large amounts of text.

Group Coordination

Coordinate multiple animated text elements:

import { AnimatedTextGroup } from '@erosnicolau/animated-text'

function Showcase() {
  return (
    <AnimatedTextGroup coordinationMode="sequential" staggerDelay={300}>
      <AnimatedText content="First text" animation="word" />
      <AnimatedText content="Second text" animation="block" />
      <AnimatedText content="Third text" animation="typewriter" />
    </AnimatedTextGroup>
  )
}

Coordination Modes

• parallel - All animations start simultaneously
• sequential - Animations start one after another
• cascade - Overlapping start times with stagger delay
• wave - Wave-like propagation effect

Internationalization

Built for multilingual applications:

<AnimatedText
  content="Bună ziua | Salut | Welcome"
  animation="phrases"
  phraseStyles={[{ className: 'text-blue-600' }, { className: 'text-green-600' }, { className: 'text-purple-600' }]}
/>

Font Scaling System

3-Level Priority Font System

The component uses a sophisticated 3-level priority system for font sizing:

Level 1: Explicit className (Highest Priority)

When you provide explicit font classes in className, they take full precedence:

<AnimatedText
  content="Custom sizing"
  className="text-2xl md:text-3xl lg:text-4xl"
  // fontPreset and fontScale are ignored
/>

Level 2: Font Presets (Medium Priority)

Use predefined responsive font combinations:

<AnimatedText
  content="Preset sizing"
  fontPreset="hero" // 'hero', 'section', 'subsection', 'body'
  // Only applies when no explicit font classes in className
/>

Available Presets:

• hero: Large display text (text-4xl md:text-5xl lg:text-6xl)
• section: Section headings (text-3xl md:text-4xl lg:text-5xl) - default
• subsection: Subsection headings (text-2xl md:text-3xl lg:text-4xl)
• body: Body text (text-lg md:text-xl lg:text-2xl)

Level 3: Font Scaling (Lowest Priority)

Proportionally scale any preset:

<AnimatedText
  content="Scaled preset"
  fontPreset="section"
  fontScale={1.2} // 20% larger than section preset
/>

<AnimatedText
  content="Smaller version"
  fontPreset="hero"
  fontScale={0.8} // 20% smaller than hero preset
/>

Semantic Elements

Control the HTML element used:

<AnimatedText
  content="Page Title"
  as="h1" // h1, h2, h3, h4, h5, h6, p, div, span
  fontPreset="hero"
/>

Advanced Props

AnimatedTextProps

| Prop | Type | Default | Description | | ------------- | --------------- | --------- | ------------------------------ | | content | string | - | Text content (required) | | animation | AnimationType | 'block' | Animation type | | allowHtml | boolean | false | Enable HTML parsing | | startDelay | number | 300 | Initial delay before animation | | itemSpacing | number | 600 | Default spacing between items |

Block Animation Props

| Prop | Type | Default | Description | | --------------- | ------------------ | ------------------------ | ------------------------ | | blockEffect | ComposableEffect | ['fadeIn', 'slide-up'] | Block animation effects | | blockDuration | number | 600 | Block animation duration | | blockEasing | AnimationEasing | 'ease-out' | Block animation easing |

Word Animation Props

| Prop | Type | Default | Description | | -------------- | ------------------ | ------------ | ---------------------- | | wordEffect | ComposableEffect | ['fadeIn'] | Word animation effects | | wordDuration | number | 400 | Duration per word | | wordSpacing | number | 200 | Time between words | | wordEasing | AnimationEasing | 'ease-out' | Word animation easing |

Typewriter Animation Props

| Prop | Type | Default | Description | | -------------------- | ------------------ | ------------ | ------------------------ | | typewriterEffect | ComposableEffect | ['fadeIn'] | Letter animation effects | | typewriterDuration | number | 200 | Duration per letter | | typewriterDelay | number | 50 | Time between letters | | typewriterEasing | AnimationEasing | 'ease-out' | Letter animation easing |

Word-Typewriter Animation Props

| Prop | Type | Default | Description | | --------------------------- | ------------------ | ------------ | ----------------------------- | | wordTypewriterEffect | ComposableEffect | ['fadeIn'] | Letter animation effects | | wordTypewriterDuration | number | 150 | Duration per letter | | wordTypewriterLetterDelay | number | 50 | Time between letters | | wordTypewriterWordDelay | number | 400 | Time delay at word boundaries | | wordTypewriterEasing | AnimationEasing | 'ease-out' | Letter animation easing |

Phrase Animation Props

| Prop | Type | Default | Description | | -------------- | --------------- | ------- | ------------------------------------ | | phraseStyles | PhraseStyle[] | [] | Individual phrase styling and timing |

Demo

The package includes a comprehensive demo showcasing all features:

import { AnimatedTextDemo } from '@erosnicolau/animated-text/demo'

function App() {
  return <AnimatedTextDemo />
}

Demo Sections Available

• Animation Types: All 5 animation modes with live examples
• Composable Effects: Mix and match effect combinations
• Ultimate Effects: 8+ effect combinations showing maximum capabilities
• Font Effects: fontSize, fontWeight, letterSpacing, lineHeight animations
• Visual Effects: Colors, shadows, borders, backgrounds
• Layout Effects: Width, height, margin, padding animations
• Typography Showcases: Real-world text animation scenarios
• Group Animations: Coordinated multi-element animations
• Creative Demos: Artistic, cinematic, gaming, and agency-style presentations
• Static Styling: Non-animated styling options
• Border Effects: Comprehensive border animation examples

CSS Import

Don't forget to import the CSS file:

import '@erosnicolau/animated-text/dist/AnimatedText.css'

TypeScript Support

Full TypeScript support with exported types:

import type { AnimatedTextProps, AnimationEffect, ComposableEffect, FPSMetrics } from '@erosnicolau/animated-text'

Performance Recommendations

1. Monitor FPS in production with getFPSMetrics()
2. Limit concurrent animations (< 10 simultaneously)
3. Prefer transform and opacity effects for best performance
4. Test on mobile devices for performance validation

License

MIT License - see package.json for details.

Contributing

This package is part of the Eros Nicolau portfolio project. For bugs or feature requests, please open an issue.

Made with ❤️ by Eros Nicolau