@saas-factory/animations

A comprehensive animation library for React and Next.js applications. Provides pre-built animations, hooks, and components to make your SaaS feel alive and engaging without bloating your bundle.

Features

✅ Micro-Interactions (button hover, press effects, state changes) ✅ Page Transitions (Next.js route changes) ✅ Data Animations (counters, progress bars, number scaling) ✅ Scroll Animations (reveal on scroll, parallax effects) ✅ Loading States (spinners, skeletons, shimmer effects) ✅ Entrance Animations (fade, slide, zoom, bounce) ✅ Gesture Animations (swipe, drag, pinch) ✅ Lottie Integration (vector animations) ✅ CSS Variable Support (theme-aware) ✅ Performance First (CSS transforms only, GPU accelerated) ✅ No Runtime Overhead (precomputed keyframes) ✅ TypeScript (full type support)

Installation

npm install @saas-factory/animations framer-motion
# or
pnpm add @saas-factory/animations framer-motion

Quick Start

Basic Animation

import { fadeIn, slideUp } from '@saas-factory/animations';

export function Hero() {
  return (
    <div className={fadeIn()}>
      <h1 className={slideUp()}>Welcome to our SaaS</h1>
    </div>
  );
}

Using Hooks

import { usePageTransition, useAnimatedCounter } from '@saas-factory/animations';

export function Stats() {
  const { isReady } = usePageTransition();
  const { displayValue } = useAnimatedCounter({ from: 0, to: 1000 });
  
  return isReady ? <div>{displayValue}</div> : <Skeleton />;
}

Using Components

import { AnimateOnScroll, AnimatedNumber } from '@saas-factory/animations';

export function Metrics() {
  return (
    <AnimateOnScroll>
      <AnimatedNumber value={4829} />
      <p>Users served</p>
    </AnimateOnScroll>
  );
}

CSS Classes

Pre-compiled Tailwind-compatible animation classes:

<div class="animate-fade-in animate-duration-500">Fade in</div>
<div class="animate-slide-up animate-delay-100">Slide up</div>
<div class="animate-bounce-in animate-duration-700">Bounce in</div>

Animation Library

Entrance Animations

• fadeIn - Opacity from 0 to 1
• fadeInUp - Fade + slide up
• fadeInDown - Fade + slide down
• slideUp - Slide from bottom
• slideDown - Slide from top
• slideLeft - Slide from right
• slideRight - Slide from left
• scaleIn - Zoom from 0 to 1
• scaleInRotate - Scale + rotate
• zoomIn - Zoom in effect
• bounceIn - Bounce entrance
• flipIn - 3D flip effect

Exit Animations

• fadeOut - Fade to transparent
• slideDown - Slide down exit
• slideUp - Slide up exit
• scaleOut - Zoom out

Idle Animations

• pulse - Gentle pulsing
• bounce - Bouncing effect
• spin - Continuous rotation
• wiggle - Side-to-side wiggle
• swing - Swinging motion
• shimmer - Shimmer/shine effect
• glow - Glow effect
• breathe - Breathing animation

Interactive Animations

• buttonPress - Button click feedback
• buttonHover - Button hover effect
• shake - Shake on error
• jiggle - Jiggle attention-grabber
• nod - Nodding motion
• shakeX - Horizontal shake
• shakeY - Vertical shake

Hooks

usePageTransition()

Animate page transitions in Next.js:

const { isReady, animateOut } = usePageTransition();

// Automatically animates in on mount
// Call animateOut() before navigation

useAnimatedCounter()

Count up/down to a target number:

const { displayValue, progress } = useAnimatedCounter({
  from: 0,
  to: 1000,
  duration: 2000,
  format: (val) => `$${val.toFixed(2)}`
});

return <span>{displayValue}</span>;

useAnimateOnScroll()

Trigger animations when element scrolls into view:

const { ref, inView } = useAnimateOnScroll({
  threshold: 0.2,
  rootMargin: '0px 0px -100px 0px'
});

return (
  <div ref={ref} className={inView ? slideUp() : ''}>
    Content appears on scroll
  </div>
);

useHoverAnimation()

Add animations on hover:

const { ref, isHovered } = useHoverAnimation({
  enterAnimation: 'scale-110',
  exitAnimation: 'scale-100'
});

return <button ref={ref}>Hover me</button>;

useGestureAnimation()

Respond to user gestures:

const { ref, isDragging, position } = useGestureAnimation({
  onDragEnd: (velocity) => {
    console.log('Swipe velocity:', velocity);
  }
});

return <div ref={ref}>Drag me</div>;

Components

<AnimateOnScroll>

Automatically animate children when scrolled into view:

<AnimateOnScroll 
  animation="fadeInUp"
  duration={500}
  delay={100}
>
  <h2>Animate on scroll</h2>
</AnimateOnScroll>

<AnimatedNumber>

Animate number changes:

<AnimatedNumber 
  value={123.45} 
  duration={1000}
  decimals={2}
  prefix="$"
/>

<FadeIn>

Simple fade-in component:

<FadeIn duration={500} delay={0}>
  <p>Fades in on mount</p>
</FadeIn>

<SkeletonLoader>

Shimmer skeleton for loading states:

<SkeletonLoader 
  width={300}
  height={20}
  borderRadius={4}
/>

<TypeWriter>

Text typing animation:

<TypeWriter 
  text="Hello World"
  speed={100}
  cursor
/>

<Reveal>

Mask reveal animation:

<Reveal direction="left" duration={500}>
  <h1>Hidden content revealed</h1>
</Reveal>

Page Transitions

Wrap your Next.js layout for smooth page transitions:

// app/layout.tsx
import { PageTransitionProvider } from '@saas-factory/animations';

export default function Layout({ children }) {
  return (
    <PageTransitionProvider>
      {children}
    </PageTransitionProvider>
  );
}

Lottie Integration

Integrate Lottie animations:

import { LottieAnimation } from '@saas-factory/animations/lottie';
import animationData from './animation.json';

export function Loading() {
  return <LottieAnimation animationData={animationData} />;
}

Configuration

Customize animation defaults:

import { configureAnimations } from '@saas-factory/animations';

configureAnimations({
  defaultDuration: 300,
  defaultEasing: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
  enableMotionReduction: true, // Respect prefers-reduced-motion
});

Tailwind Integration

Import animation utilities in your globals.css:

@import '@saas-factory/animations/tailwind.css';

Then use in HTML:

<div class="animate-fade-in animate-duration-500 animate-delay-100">
  Animated with classes
</div>

Performance Tips

• Use CSS animations for simple effects
• Batch animations with requestAnimationFrame
• Lazy load Lottie animations
• Use will-change sparingly
• Test on mobile devices
• Respect prefers-reduced-motion

Accessibility

All animations respect user preferences:

@media (prefers-reduced-motion: reduce) {
  /* Animations disabled */
}

Examples

Loading Spinner

import { spin } from '@saas-factory/animations';

export function Spinner() {
  return <div className={`w-8 h-8 border-4 border-blue-500 rounded-full ${spin()}`} />;
}

Staggered List

import { stagger, fadeInUp } from '@saas-factory/animations';

export function List({ items }) {
  return (
    <ul className={stagger('fadeInUp', items.length)}>
      {items.map((item, i) => (
        <li key={i} className={fadeInUp()} style={{ animationDelay: `${i * 100}ms` }}>
          {item}
        </li>
      ))}
    </ul>
  );
}

Scroll Progress Indicator

import { useScrollProgress } from '@saas-factory/animations';

export function ReadingProgress() {
  const progress = useScrollProgress();
  
  return (
    <div 
      className="h-1 bg-blue-500"
      style={{ width: `${progress * 100}%` }}
    />
  );
}

Browser Support

• Chrome/Edge (latest)
• Firefox (latest)
• Safari (latest)
• Mobile browsers (iOS Safari, Chrome Mobile)

Dependencies

• framer-motion (optional, for advanced animations)
• react (18.0+)

License

MIT