animex/README.md

Modern animation-on-scroll library with optional GSAP support

# 🎉 AnimeX — Scroll Animation Library

[![npm version](https://img.shields.io/npm/v/animex.svg?style=flat-square)](https://www.npmjs.com/package/animex)
[![GitHub stars](https://img.shields.io/github/stars/Theusama1183/animex.svg?style=social)](https://github.com/Theusama1183/animex)
[![License](https://img.shields.io/npm/l/animex)](https://github.com/Theusama1183/animex/blob/main/LICENSE)
[![unpkg](https://img.shields.io/badge/CDN-unpkg-brightgreen)](https://unpkg.com/animex/)

> **AnimeX** is a lightweight, plug-and-play scroll animation library for modern websites. Designed for performance and simplicity with support for 100+ stunning animations and optional GSAP integration.

---

## 🌐 Live Demo

👉 [Explore the Animation Gallery »](https://animex.beeoceans.com/)

---

## 🚀 Quick Install

### 📦 npm

```bash
npm install animex
```

### 🌐 CDN (via unpkg)

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/animex/dist/animex.min.css"
/>
<script src="https://cdn.jsdelivr.net/npm/animex/dist/animex.min.js"></script>
```

---

## ✨ Basic Usage

### HTML Markup

```html
<div animex="fade-up" animex-delay="300" animex-duration="1000">
  Hello AnimeX!
</div>
```

### JavaScript Init

```js
AnimeX.init({
  useGSAP: true,
  once: true,
  offset: 100,
  delay: 100,
  debug: true,
});
```

---

## 🔧 Configuration Options

| Option     | Type    | Default  | Description                               |
| ---------- | ------- | -------- | ----------------------------------------- |
| `offset`   | Number  | `120`    | Distance from bottom of screen to trigger |
| `duration` | Number  | `800`    | Animation duration in milliseconds        |
| `easing`   | String  | `'ease'` | CSS easing value                          |
| `once`     | Boolean | `false`  | Animate only once                         |
| `useGSAP`  | Boolean | `false`  | Use GSAP if available                     |
| `delay`    | Number  | `0`      | Adds incremental delay (ms) per element   |
| `debug`    | Boolean | `false`  | Highlights target elements on scroll      |

---

## 🎬 Animation Types

Over 100 pre-built effects including:

- ✅ Fade, Slide, Zoom
- ✅ Flip, Rotate, Skew
- ✅ Bounce, Pulse, Shake
- ✅ GSAP-powered transforms (optional)

View the full animation gallery → [Demo](https://animex.beeoceans.com/)
`

---

## 📘 API Reference

### `AnimeX.init(config)` → Instance

Initializes AnimeX with the given configuration.

#### Parameters:

- `config` (`object`) — configuration object with the following keys:
  - `offset`: Number (scroll trigger offset in pixels)
  - `duration`: Number (default animation duration in ms)
  - `easing`: String (default CSS easing)
  - `once`: Boolean (animate only once)
  - `useGSAP`: Boolean (use GSAP if loaded)
  - `delay`: Number (incremental delay between elements in ms)
  - `debug`: Boolean (adds outline for debug)

### `AnimeX.refresh()`

Forces re-scan of all `[animex]` elements and re-initializes observers.

---

## 📄 License

[MIT License](LICENSE) © 2025 [Usama Adeel](https://github.com/Theusama1183)

---

> Made with ❤️ to help developers craft delightful web experiences with zero dependencies.