# Zing Animation Library

Zing is a lightweight animation library for both **Vanilla JavaScript** and **React**, inspired by GSAP and Framer Motion. It provides a powerful, clean API to animate DOM elements or React components using both **imperative** and **declarative** approaches.

## Table of Contents

1. [Installation](#installation)
2. [Core Concepts](#core-concepts)
3. [Vanilla JavaScript Usage](#vanilla-javascript-usage)
4. [React Usage](#react-usage)
   - [ZingComponent](#zingcomponent)
   - [useAnimation Hook](#useanimation-hook)
5. [Animation Properties](#animation-properties)
6. [Easing Functions](#easing-functions)
7. [Advanced Patterns](#advanced-patterns)
8. [Troubleshooting](#troubleshooting)

---

## Installation

Install via npm or yarn:

```bash
npm install zing-animation
# or
yarn add zing-animation

Note: If you encounter a dependency issue related to React versions (especially with React 19+), use the following command to bypass strict peer dependency resolution:

npm install zing-animation --legacy-peer-deps

Core Concepts

Zing Animation supports two paradigms:

• Imperative API – Direct control over animation via functions (for Vanilla JS).
• Declarative API – React components and hooks for more expressive animation flows.

Vanilla JavaScript Usage

Basic Animation

import { zing } from 'zing-animation';

const element = document.getElementById('my-element');

// Animate to new values
zing.to(element, {
  x: 100,
  opacity: 0.5,
  duration: 1,
  ease: 'easeOut',
  onComplete: () => console.log('Animation complete!')
}).play();

// Animate from values
zing.from(element, {
  x: -100,
  opacity: 0,
  duration: 0.5
}).play();

// Chained animations
zing.to(element, { x: 100, duration: 0.5 })
   .to(element, { y: 50, duration: 0.5 })
   .play();

Animation Controls

const animation = zing.to(element, { x: 100 });

animation.play();
animation.pause();
animation.restart();

// Timeline
const timeline = zing.sequence();
timeline.add(zing.to(element1, { x: 100 }));
timeline.add(zing.to(element2, { y: 50 }));
timeline.play();

React Usage

ZingComponent

A declarative component for defining entry/exit animations:

import { ZingComponent } from 'zing-animation';

function MyComponent() {
  return (
    <ZingComponent
      initial={{ opacity: 0, scale: 0.5 }}
      animate={{ opacity: 1, scale: 1 }}
      transition={{ duration: 0.5, ease: 'easeOut' }}
      style={{ width: 100, height: 100, background: 'blue' }}
    >
      Animated Content
    </ZingComponent>
  );
}

useAnimation Hook

Hook for full animation control inside components:

import { useAnimation } from 'zing-animation';

function MyComponent() {
  const ref = useRef();

  // Simple animation
  useAnimation(ref, {
    from: { opacity: 0 },
    to: { opacity: 1, x: 100 }
  });

  // Callback-based dynamic animation
  useAnimation(ref, () => ({
    from: { opacity: 0, y: -20 },
    to: { opacity: 1, y: 0, duration: 0.8, onComplete: () => console.log('Done!') }
  }));

  return <div ref={ref}>Animated Element</div>;
}

Animation Properties

Transform Properties

• x: Horizontal translation (px)
• y: Vertical translation (px)
• scale: Scaling (number)
• rotate: Rotation (deg)
• skewX, skewY: Skew transforms (deg)

Style Properties

• opacity
• width, height
• backgroundColor
• color
• Any other animatable CSS property

Controls

• duration (seconds, default 0.5)
• delay (seconds)
• ease (see Easing Functions)
• onComplete (callback)
• repeat (number)
• yoyo (boolean, reverse on repeat)

Easing Functions

Zing provides a variety of easing presets:

• linear
• easeIn, easeOut, easeInOut
• easeInCubic, easeOutCubic
• easeInElastic, easeOutElastic
• easeInBack, easeOutBack

<ZingComponent
  animate={{ x: 100 }}
  transition={{ ease: 'easeOutBack' }}
/>

Advanced Patterns

Staggered Animations

function List() {
  const items = [1, 2, 3, 4];
  const refs = items.map(() => useRef());

  useEffect(() => {
    refs.forEach((ref, i) => {
      zing.to(ref.current, {
        x: 100,
        opacity: 1,
        delay: i * 0.1,
        duration: 0.5
      }).play();
    });
  }, []);

  return (
    <div>
      {items.map((item, i) => (
        <div key={item} ref={refs[i]} style={{ opacity: 0 }}>
          Item {item}
        </div>
      ))}
    </div>
  );
}

Scroll-triggered Animations

function ScrollComponent() {
  const ref = useRef();

  useEffect(() => {
    const onScroll = () => {
      const rect = ref.current.getBoundingClientRect();
      const progress = Math.min(rect.top / window.innerHeight, 1);

      zing.to(ref.current, {
        x: progress * 100,
        opacity: 1 - progress
      }).play();
    };

    window.addEventListener('scroll', onScroll);
    return () => window.removeEventListener('scroll', onScroll);
  }, []);

  return <div ref={ref}>Scroll me!</div>;
}

Troubleshooting

Animation Not Working?

• Ensure elements are visible and styled correctly.
• Avoid conflicting styles (overflow: hidden on parents may hide animations).
• Use camelCase CSS properties (e.g. backgroundColor).

Performance Issues?

• Use transform properties (x, y, scale) over layout props (margin, width).
• Add will-change: transform in CSS for smoother animations.
• Avoid animating large numbers of elements simultaneously.

React Warnings or Errors?

• Always use useEffect for side-effects like animations.
• Clean up listeners or animations inside the useEffect return.
• Use useCallback when passing animation functions as dependencies.

📦 Links

• GitHub: https://github.com/sarcaxticlarka/zing-animation
• NPM: https://www.npmjs.com/package/zing-animation

Created with ❤️ to bring motion to the web.