https://github.com/usaljs/usal
USAL.js - Ultimate Scroll Animation Library - Lightweight, powerful, wonderfully simple ✨
https://github.com/usaljs/usal
animation css-animations intersection-observer javascript scroll-animations scroll-library web-animation
Last synced: 3 months ago
JSON representation
USAL.js - Ultimate Scroll Animation Library - Lightweight, powerful, wonderfully simple ✨
- Host: GitHub
- URL: https://github.com/usaljs/usal
- Owner: usaljs
- License: mit
- Created: 2025-09-02T16:20:55.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-10-03T09:42:47.000Z (3 months ago)
- Last Synced: 2025-10-05T15:33:27.147Z (3 months ago)
- Topics: animation, css-animations, intersection-observer, javascript, scroll-animations, scroll-library, web-animation
- Language: JavaScript
- Homepage: https://usal.dev/
- Size: 5.43 MB
- Stars: 106
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
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://npmjs.com/package/usal) [](https://discord.usal.dev/)
[](https://www.cloudflare.com/) [](https://jsdelivr.com) [](https://github.com/sponsors/italoalmeida0)
## ✨ 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
import { USALPlugin } from '@usal/vue';
createApp(App).use(USALPlugin).mount('#app');
//for Nuxt
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/usaljs/usal/wiki/API-Documentation) or https://usal.dev/#api
## 🎲 Demos
## 📊 Packages Overview
| Package | Version |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `usal` |  |
| `@usal/react` |  |
| `@usal/solid` |  |
| `@usal/svelte` |  |
| `@usal/vue` |  |
| `@usal/lit` |  |
| `@usal/angular` |  |
## 📈 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))