motionx

Unified Motion Engine for React & React Native

One component for all animation formats: Lottie, GIF, MP4, WebM

🎯 Why motionx?

Stop juggling multiple animation libraries. motionx provides a single <Motion> component that works across all formats and platforms.

Before (Multiple Libraries)	After (motionx)
lottie-react-native	✅ One Component
lottie-web	✅ One API
react-native-video	✅ React + RN
Custom GIF handlers	✅ Auto-detect format

---

🚀 Installation

npm install @thewoowon/motionx
# or
yarn add @thewoowon/motionx

---

📦 Quick Start

import { Motion } from '@thewoowon/motionx';

function App() {
  return (
    <Motion
      source={require('./animation.json')}
      autoPlay
      loop
      width={200}
      height={200}
      onFinish={() => console.log('Done!')}
      fallback={<div>Loading...</div>}
    />
  );
}

That's it! motionx automatically detects the format and renders it correctly.

---

✨ Features

• 🎨 Unified API - One component for all formats
• 🔄 Auto-detection - Automatically detects Lottie, GIF, MP4, WebM
• 📱 Cross-platform - Works on React Web & React Native
• ⚡ Zero config - Just pass the source
• 🎭 Fallback support - Show loading states easily
• 🎬 Full control - loop, autoPlay, speed, callbacks
• 📦 Tiny - Minimal dependencies

---

🎬 Supported Formats

Format	Web	React Native	Notes
Lottie (JSON)	✅	✅	Full support
GIF	✅	✅	Native rendering
MP4	✅	⚠️	RN needs react-native-video
WebM	✅	❌	Web only

---

📖 API Reference

Props

interface MotionProps {
  // Source (required)
  source: string | object | number;

  // Playback
  loop?: boolean;           // Default: false
  autoPlay?: boolean;       // Default: true
  speed?: number;           // Default: 1.0

  // Size
  width?: number;
  height?: number;

  // UI
  fallback?: ReactNode;     // Loading/error state
  style?: CSSProperties | ViewStyle;
  className?: string;       // Web only

  // Callbacks
  onPlay?: () => void;
  onPause?: () => void;
  onFinish?: () => void;
  onError?: (error: Error) => void;

  // Testing
  testID?: string;
}

---

🔥 Examples

Lottie Animation

<Motion
  source={require('./logo.json')}
  autoPlay
  loop
  width={300}
  height={300}
/>

From URL

<Motion
  source="https://assets.lottiefiles.com/packages/lf20_example.json"
  autoPlay
  fallback={<Spinner />}
/>

GIF

<Motion
  source={require('./loading.gif')}
  width={100}
  height={100}
/>

Video (MP4)

<Motion
  source="https://example.com/video.mp4"
  autoPlay
  loop
  width={640}
  height={360}
  onError={(err) => console.error(err)}
/>

React Native

import { Motion } from '@thewoowon/motionx';
import { View } from 'react-native';

<View>
  <Motion
    source={require('./splash.json')}
    autoPlay
    loop
    width={200}
    height={200}
    style={{ marginTop: 20 }}
  />
</View>

---

🎯 How It Works

1. Format Detection - Automatically detects format from file extension or content
2. Platform Detection - Chooses Web or React Native renderer
3. Optimized Rendering - Uses the best library for each format:
   • Lottie: lottie-web (Web) / lottie-react-native (RN)
   • GIF: <img> (Web) / <Image> (RN)
   • Video: <video> (Web) / react-native-video (RN)*

*Note: React Native video requires installing react-native-video separately

---

🛠️ Advanced Usage

Custom Styling

<Motion
  source={require('./hero.json')}
  autoPlay
  loop
  style={{
    borderRadius: 16,
    boxShadow: '0 4px 20px rgba(0,0,0,0.1)',
    background: '#f5f5f5',
  }}
/>

Controlled Playback

function ControlledAnimation() {
  const [playing, setPlaying] = useState(false);

  return (
    <>
      <Motion
        source={require('./click.json')}
        autoPlay={playing}
        loop={false}
        onFinish={() => setPlaying(false)}
      />
      <button onClick={() => setPlaying(true)}>
        Play
      </button>
    </>
  );
}

Error Handling

<Motion
  source={unknownSource}
  fallback={<div>Failed to load animation</div>}
  onError={(error) => {
    console.error('Animation error:', error);
    analytics.track('animation_error', { error });
  }}
/>

---

📱 React Native Setup

For React Native projects, ensure you have the peer dependencies:

npm install lottie-react-native
# For video support (optional)
npm install react-native-video

Then link native modules:

cd ios && pod install

---

🎭 TypeScript Support

Full TypeScript support included:

import { Motion, MotionProps, MotionFormat } from '@thewoowon/motionx';

const props: MotionProps = {
  source: './animation.json',
  autoPlay: true,
  loop: true,
};

---

🗺️ Roadmap

v0.1 (Current)

• ✅ Lottie, GIF, MP4, WebM support
• ✅ React & React Native
• ✅ Auto format detection
• ✅ Unified API

v0.2 (Coming Soon)

• Rive support
• SpriteSheet animations
• Frame control (seek, progress)
• Animation preloading

v0.3+

• Skeleton animations
• SVG animations
• Canvas-based rendering
• Performance optimizations

---

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

---

📄 License

MIT © eternalgridx

---

💡 Philosophy

"애니메이션은 파일 포맷이 아니라 'Motion' 개념이다."

motionx는 개발자가 구현에 집중하도록, 포맷의 복잡함을 숨깁니다.

디자이너가 파일만 던져주면, 개발자는 <Motion>만 쓰면 됩니다. 끝.