https://github.com/mirayatech/mochi-motion
https://github.com/mirayatech/mochi-motion
Last synced: 11 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/mirayatech/mochi-motion
- Owner: mirayatech
- License: mit
- Created: 2025-07-13T19:27:44.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-07-13T20:25:27.000Z (12 months ago)
- Last Synced: 2025-07-13T22:09:58.750Z (12 months ago)
- Language: TypeScript
- Size: 3.03 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🍡 Mochi Motion
**Professional spring animations for React & Next.js that feel like butter.**
Mochi Motion brings world-class animation to your React applications with zero configuration. Built on Framer Motion with intelligent defaults, it delivers the smooth, bouncy animations you see in the best modern web apps.
## ✨ Why Mochi Motion?
**It just works.** Drop it in your React or Next.js app and get beautiful animations instantly. No complex configuration, no performance headaches, no framework lock-in.
- **Universal compatibility** — Works with React, Next.js App Router, Pages Router, Vite, and Create React App
- **Professional spring physics** — Four carefully tuned presets plus full customization
- **Performance optimized** — Intersection Observer API with smart defaults
- **TypeScript native** — Written in TypeScript with comprehensive type definitions
- **Production ready** — 8KB compressed, battle-tested in real applications
## 📦 Installation
```bash
npm install mochi-motion framer-motion react-intersection-observer
```
That's it. No additional setup required.
## 🚀 Quick Start
### React (Vite, CRA, or any React app)
```tsx
import { ReactTransition, RevealOnScroll } from 'mochi-motion'
function App() {
return (
Welcome to the future
)
}
```
### Next.js App Router
```tsx
// app/layout.tsx
import { AppRouterTransition } from 'mochi-motion'
export default function RootLayout({ children }) {
return (
{children}
)
}
```
### Next.js Pages Router
```tsx
// pages/_app.tsx
import { PageTransition } from 'mochi-motion'
export default function App({ Component, pageProps }) {
return (
)
}
```
## 🎬 Animation Effects
Mochi Motion includes eight carefully crafted animation effects. Each one uses professional spring physics that respond naturally to user interaction.
### Fade Animations
```tsx
Content slides up smoothly
Content drops down elegantly
Content sweeps in from the right
Content glides in from the left
```
### Scale Animations
```tsx
Content zooms in with perfect timing
Content emerges from larger scale
```
### Special Effects
```tsx
Content focuses into clarity
Content spins into position
```
## ⚙️ Spring Physics
The magic happens in the spring configurations. We've spent months tuning these presets to feel just right in real applications.
### Gentle
Soft, premium feel. Perfect for luxury brands and professional interfaces.
```tsx
Elegant and refined
```
### Wobbly
Bouncy and engaging. Adds personality without being distracting.
```tsx
Fun and interactive
```
### Stiff
Quick and responsive. Great for dashboards and productivity apps.
```tsx
Snappy and efficient
```
### Slow
Deliberate and thoughtful. Commands attention for important content.
```tsx
Considered and impactful
```
## 🔥 Advanced Usage
### Custom Spring Physics
When the presets aren't enough, dive into the physics:
```tsx
```
### Staggered Animations
Create cascading effects that guide user attention:
```tsx
function FeatureGrid({ features }) {
return (
{features.map((feature, index) => (
))}
)
}
```
### Performance Optimization
Fine-tune when animations trigger:
```tsx
```
## 💙 TypeScript Support
Mochi Motion is written in TypeScript with comprehensive type definitions. Everything is fully typed for the best developer experience.
### Core Types
```typescript
type AnimationEffect =
| 'fade-up' | 'fade-down' | 'fade-left' | 'fade-right'
| 'scale-up' | 'scale-down'
| 'blur-up' | 'rotate-up'
type SpringPreset = 'gentle' | 'wobbly' | 'stiff' | 'slow' | 'custom'
interface SpringConfig {
stiffness?: number // 80-300
damping?: number // 8-30
mass?: number // 0.8-1.5
}
```
### Component Props
```typescript
interface RevealOnScrollProps {
effect?: AnimationEffect
preset?: SpringPreset
spring?: SpringConfig
delay?: number
distance?: number
scale?: number
threshold?: number
triggerOnce?: boolean
children: React.ReactNode
className?: string
}
```
### Type-Safe Usage
```tsx
import { RevealOnScroll, SpringConfig } from 'mochi-motion'
const customSpring: SpringConfig = {
stiffness: 150,
damping: 15,
mass: 1.1
}
function TypedComponent() {
return (
Perfectly type-safe animations
)
}
```
## 🌍 Real-World Examples
### Landing Page Hero
```tsx
function Hero() {
return (
Your Product Name
The future of everything, available today.
Get Started
)
}
```
### Feature Showcase
```tsx
function Features() {
const features = [
{ title: "Lightning Fast", description: "Built for speed" },
{ title: "Rock Solid", description: "Never breaks" },
{ title: "Always Fresh", description: "Regular updates" }
]
return (
{features.map((feature, i) => (
{feature.title}
{feature.description}
))}
)
}
```
### Testimonial Section
```tsx
function Testimonials() {
return (
What people are saying
)
}
```
## 🔄 Migration Guide
### From Pages Router to App Router
**Before:**
```tsx
// pages/_app.tsx
import { PageTransition } from 'mochi-motion'
export default function App({ Component, pageProps }) {
return (
)
}
```
**After:**
```tsx
// app/layout.tsx
import { AppRouterTransition } from 'mochi-motion'
export default function RootLayout({ children }) {
return (
{children}
)
}
```
## ⚡ Performance Notes
Mochi Motion is built for production. Here's what we've optimized:
- **Intersection Observer API** for efficient scroll detection
- **Hardware acceleration** for all animations
- **Tree shaking support** to keep bundles small
- **Smart defaults** that work in 90% of cases
- **Minimal re-renders** with optimized React patterns
### Bundle Size
- **8.8 KB compressed** (smaller than most images)
- **Tree shakable** — import only what you use
- **Zero runtime dependencies** — peer dependencies only
## 🌐 Browser Support
Mochi Motion works in all modern browsers:
- **Chrome/Edge**: 88+
- **Firefox**: 85+
- **Safari**: 14+
- **React**: 17.0.0+
- **Next.js**: 12.0.0+
## 📖 API Reference
### RevealOnScroll
The primary component for scroll-triggered animations.
| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `effect` | `AnimationEffect` | `'fade-up'` | Animation type |
| `preset` | `SpringPreset` | `'gentle'` | Spring physics preset |
| `spring` | `SpringConfig` | — | Custom spring configuration |
| `delay` | `number` | `0` | Animation delay in seconds |
| `distance` | `number` | `50` | Slide distance in pixels |
| `scale` | `number` | `0.8` | Scale factor for scale animations |
| `threshold` | `number` | `0.1` | Intersection observer threshold |
| `triggerOnce` | `boolean` | `true` | Whether to animate only once |
### Page Transition Components
| Component | Use Case |
|-----------|----------|
| `ReactTransition` | Universal React apps (Vite, CRA) |
| `AppRouterTransition` | Next.js 13+ App Router |
| `PageTransition` | Next.js Pages Router |
All transition components accept:
- `children`: React node to animate
- `preset`: Spring physics preset
- `className`: Additional CSS classes
## 🤝 Contributing
Mochi Motion is open source and welcomes contributions. Found a bug or have a feature request? [Open an issue](https://github.com/mirayatech/mochi-motion/issues).
## 📄 License
MIT License © 2025 [@mirayatech](https://github.com/mirayatech)