https://github.com/italoalmeida0/usal
USAL.js - Ultimate Scroll Animation Library - Lightweight, powerful, wonderfully simple ✨
https://github.com/italoalmeida0/usal
animation css-animations intersection-observer javascript scroll-animations scroll-library web-animation
Last synced: about 2 months ago
JSON representation
USAL.js - Ultimate Scroll Animation Library - Lightweight, powerful, wonderfully simple ✨
- Host: GitHub
- URL: https://github.com/italoalmeida0/usal
- Owner: italoalmeida0
- License: mit
- Created: 2025-09-02T16:20:55.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2025-09-09T22:04:26.000Z (about 2 months ago)
- Last Synced: 2025-09-10T01:03:00.904Z (about 2 months ago)
- Topics: animation, css-animations, intersection-observer, javascript, scroll-animations, scroll-library, web-animation
- Language: JavaScript
- Homepage: https://usal.dev/
- Size: 2.93 MB
- Stars: 37
- Watchers: 0
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- fucking-awesome-angular - usal - Framework agnostic ultimate scroll animation library. (Third Party Components / Scroll)
- awesome-angular - usal - Framework agnostic ultimate scroll animation library. (Third Party Components / Scroll)
README
**Ultimate Scroll Animation Library - Lightweight, powerful, wonderfully simple ✨**
**Works with React, Solid, Svelte, Vue, Lit, Angular, Vanilla JS and more**
**[> usal.dev/](https://usal.dev/)**
[](https://cloudflare.com)
[](https://jsdelivr.com)
[](https://npmjs.com/package/usal)
## ✨ Features
- 🎯 **40+ animations** (fade, zoom, flip with all directions)
- 📝 **Text animations** (split by word/letter)
- 🔢 **Number counters**
- 🎨 **Text effects** (shimmer, fluid)
- 📦 **Only 8KB Gzipped**
- 🚀 **Zero dependencies**
- ♾ **60fps performance**
- 🪤 **Web components supported**
- 🔧 **Framework agnostic**
- ⚡ **CDN powered** by jsDelivr & Cloudflare
## 📦 Installation
### CDN (Quickstart)
```html
```
### NPM
```bash
npm install usal
# Framework-specific packages
npm install @usal/react # For React/Next.js
npm install @usal/solid # For Solid/SolidStart
npm install @usal/svelte # For Svelte/SvelteKit
npm install @usal/vue # For Vue/Nuxt
npm install @usal/lit # For Lit
npm install @usal/angular # For Angular
```
## 🚀 Framework Setup
### ⬛ React (Next.js)
```jsx
import { USALProvider } from '@usal/react';
{children};
```
### 🟦 Solid (SolidStart)
```jsx
import { USALProvider } from '@usal/solid';
{props.children};
```
### 🟧 Svelte (SvelteKit)
```js
import { usal } from '@usal/svelte';
// USAL auto-initializes globally
```
### 🟩 Vue (Nuxt)
```js
export default defineNuxtConfig({
modules: ['@usal/vue/nuxt']
```
### 🟪 Lit
```js
import { usal } from '@usal/lit';
// USAL auto-initializes globally
```
### 🟥 Angular
```js
import { USALModule } from '@usal/angular';
@Component({imports: [USALModule]})
export class AppComponent
```
## 📐 Basic Usage
```html
Fade from bottom
Zoom in
Flip from right
```
## [📖 Complete API Documentation](https://github.com/italoalmeida0/usal/wiki/API-Documentation) or https://usal.dev/#api
## 🎲 Demos
## 📊 Packages Overview
| Package | Description | Version |
| --------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `usal` | Core library (Vanilla JS) |  |
| `@usal/react` | React integration |  |
| `@usal/solid` | Solid integration |  |
| `@usal/svelte` | Svelte integration |  |
| `@usal/vue` | Vue integration |  |
| `@usal/lit` | Lit integration |  |
| `@usal/angular` | Angular integration |  |
## 📈 JavaScript Animation Frameworks Comparison (2025)
### Performance & Size Comparison
| Framework | Bundle Size (gzip) | React | Vue | Angular | Svelte | Solid | Lit | Vanilla |
| -------------- | ------------------ | --------- | --------- | --------- | --------- | --------- | --------- | ------- |
| **🚀 USAL.js** | **~8KB** | ✅ Native | ✅ Native | ✅ Native | ✅ Native | ✅ Native | ✅ Native | ✅ |
| Motion One | Variable (~small) | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
| GSAP | ~28KB | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Anime.js v4 | ~27KB | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Lottie | ~60KB | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ⚠️ | ✅ |
| AOS | ~8KB | ⚠️ | ⚠️ | ⚠️ | ❌ | ❌ | ❌ | ✅ |
| SAL.js | ~2.7KB | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
### Feature Comparison
| Framework | Split (Letters/Words/Items) | Counters | Scroll Trigger | Timeline | SVG | Learning |
| ----------- | --------------------------- | --------- | -------------- | ----------- | --------- | ------------- |
| **USAL.js** | ✅ Core | ✅ Core | ✅ Core | ✅ Core | ❌ | **Very Easy** |
| Motion | ❌ | ❌ | ✅ Core | ⚠️ Variants | ✅ Core | Medium |
| GSAP | ⚠️ Plugin | ⚠️ Plugin | ✅ Plugin | ✅ Advanced | ⚠️ Plugin | Complex |
| Anime.js v4 | ✅ Core | ✅ Core | ✅ Core | ✅ Core | ✅ Core | Medium |
| Lottie | ⚠️ via AE | ⚠️ via AE | ❌ | ✅ Core | ✅ Core | Complex |
| AOS | ❌ | ❌ | ✅ Core | ❌ | ❌ | Very Easy |
| SAL.js | ❌ | ❌ | ✅ Core | ❌ | ❌ | Very Easy |
**Legend:**
- ✅ Native/Core support
- ⚠️ Plugin/Wrapper required
- ❌ Not supported
## 🙏 Acknowledgments
USAL.js was inspired by:
- **[AOS.js](https://github.com/michalsnik/aos)** - Pioneering attribute-based animations
- **[SAL.js](https://github.com/mciastek/sal)** - Lightweight performance optimization
- **[Tailwind CSS](https://tailwindcss.com)** - Utility-first naming conventions
---
## 📄 License
MIT License © 2025 Italo Almeida ([@italoalmeida0](https://github.com/italoalmeida0))