Tiny Framework-Agnostic Scroll Animation Library – USAL.js

USAL.js is a lightweight scroll animation library that creates smooth, performant animations triggered by viewport visibility across any JavaScript framework or vanilla implementation.

It currently delivers 40+ animation types, text effects, number counters, and split animations while maintaining 60fps performance.

The library works perfectly with any JavaScript frameworks and libraries, including React, Vue, Svelte, Angular, Lit, Solid, or vanilla JavaScript, through a simple data attribute API that feels natural regardless of your tech stack.

See It In Action:

Features:

• 40+ animation variations: Includes fade, zoom, flip animations with directional controls (up, down, left, right, diagonal combinations).
• Text animation system: Split animations by words, letters, or child elements with customizable delays and effects.
• Number counter animations: Animate numeric values from zero to target with decimal and comma formatting support.
• Special text effects: Shimmer and fluid weight effects for enhanced typography animations.
• Performance optimization: 60fps animations with configurable thresholds and concurrent animation limits.
• Zero dependencies: Pure JavaScript implementation with no external requirements.

Use Cases:

• Marketing landing pages: Create engaging product showcases with staggered animations that reveal content as users scroll.
• Portfolio and agency websites: Animate project galleries, testimonials, and service sections to create professional presentations that capture visitor attention without overwhelming performance budgets.
• Dashboard and analytics interfaces: Implement smooth number counter animations for statistics, KPIs, and metrics that provide visual feedback when data updates or comes into view.
• Documentation and educational content: Use text split animations to reveal complex information progressively, making technical content more digestible and engaging for readers.

How to use it:

1. Install the core library and the specific package for your framework.

## Core package
npm install usal

# Framework-specific packages:
npm install @usal/react
npm install @usal/solid
npm install @usal/svelte
npm install @usal/vue
npm install @usal/lit
npm install @usal/angular

2. Import usal into your project.

// React (Next.js)
import { USALProvider } from '@usal/react';
<USALProvider>{children}</USALProvider>

// Solid (SolidStart)
import { USALProvider } from '@usal/solid';
<USALProvider>{props.children}</USALProvider>

// Svelte (SvelteKit)
import { usal, createUSAL } from '@usal/svelte';
const usalInstance = createUSAL();

// Vue (Nuxt)
export default defineNuxtConfig({
modules: ['@usal/vue/nuxt']

// Lit
import { usal, useUSAL } from '@usal/lit';
const usalInstance = useUSAL();

// Angular
import { USALModule } from '@usal/angular';
@Component({imports: [USALModule]})
export class AppComponent

3. For vanilla JavaScript, including the CDN script is all you need.

<script src="https://cdn.usal.dev/latest"></script>

4. USAL.js works primarily through an HTML attribute, data-usal. You pass a string of space-separated values that define the animation and its modifiers.

<!-- A simple fade-up animation -->
<div data-usal="fade-u">Content</div>

<!-- A zoom-in animation with a custom duration -->
<div data-usal="zoomin duration-800">With duration</div>

<!-- A more complex animation with a delay and blur effect -->
<div data-usal="flip-r delay-500 blur">Complex</div>

<!-- A counter that counts up to 1234 -->
<div data-usal="count-[1234] duration-2000">1234</div>

<!-- A text fluid effect -->

<!-- A text shimmer effect -->
<h2 data-usal="text-fluid split-letter duration-2500">Fluid Weight</h2>
<p data-usal="text-shimmer split-letter duration-1000">Shimmer Letter</p>

<!-- Svelte (SvelteKit) -->
<div use:usal={'fade duration-500'}>Content</div>

<!-- Vue (Nuxt) -->
<div v-usal="'fade duration-500'">Content</div>

<!-- Lit -->
<div ${usal('fade duration-500')}>Content</div>

<!-- Angular -->
<div [usal]="'fade duration-500'">Content</div>

5. The data-usal-id attribute is useful for single-page applications. In frameworks like React or Vue, components can re-render, causing animations to re-trigger. By assigning a static data-usal-id, you tell USAL.js that it’s the same element, preventing it from re-animating on every render.

<!-- This will re-animate if the component re-renders -->
<div data-usal="fade-u">Auto ID</div>

<!-- This will NOT re-animate on re-renders -->
<div data-usal="fade-u" data-usal-id="my-unique-element">Fixed ID</div>

6. Global configuration options.

window.USAL.config({
  maxConcurrent: 100,    // Maximum concurrent animations
  duration: 1000,        // Default duration in milliseconds
  delay: 0,              // Default delay in milliseconds
  threshold: 30,         // Visibility threshold percentage
  splitDelay: 30,        // Default split animation delay
  once: false            // Run animations only once
});

Animation Types:

USAL.js provides four main animation categories with directional variants. Fade animations create opacity transitions with optional movement:

• fade: Simple opacity transition
• fade-u, fade-d, fade-l, fade-r: Fade with directional movement
• fade-ul, fade-ur, fade-dl, fade-dr: Diagonal fade animations

Zoom animations scale elements during transitions:

• zoomin, zoomout: Scale from/to center
• zoomin-u, zoomout-d: Zoom with directional bias
• zoomin-ul, zoomout-dr: Diagonal zoom effects

Flip animations rotate elements along different axes:

• flip: Standard flip animation
• flip-u, flip-d: Vertical axis flips
• flip-l, flip-r: Horizontal axis flips

Text and Split Animations

Text animations provide granular control over individual words, letters, or child elements. Split animations break content into animated parts:

<h2 data-usal="split-word fade-r split-delay-100">
  Each word animates separately
</h2>

<p data-usal="split-letter zoomin split-delay-50">
  Individual letter animations
</p>

<div data-usal="split-item fade-u">
  <span>Child</span>
  <span>Elements</span>
  <span>Animate</span>
</div>

Split animations support custom delays between elements and can combine with any base animation type.

Number Counter Animations

Counter animations smoothly transition numeric values from zero to the target number:

<div data-usal="count-[1234] duration-2000">1234</div>
<div data-usal="count-[98.5] duration-2500">98.5%</div>
<div data-usal="count-[42,350] duration-3000">$42,350</div>

The counter system automatically handles decimal places and comma formatting. It’s suitable for currency, percentages, and statistical displays.

Special Text Effects

USAL.js includes advanced text effects for enhanced typography. These work best with split-letter animations:

<h2 data-usal="text-fluid split-letter duration-2500">
  Fluid Weight Effect
</h2>

<p data-usal="text-shimmer split-letter duration-1000">
  Shimmer Animation
</p>

Animation Modifiers

Modifiers control timing, easing, and behavior. Duration accepts millisecond values:

• duration-500, duration-1000, duration-2000: Custom animation timing

Delay modifiers offset animation start times:

• delay-200, delay-500, delay-1000: Millisecond delays

Easing functions control animation curves:

• linear, ease, ease-in, ease-out: Standard CSS easing

Behavioral modifiers change animation behavior:

• once: Run animation only once, don’t repeat on scroll
• blur: Add blur effect during animation
• threshold-50: Trigger animation when 50% of element is visible

FAQs:

Q: How does USAL.js affect website performance, especially on long pages with many animations?
A: It has a minimal performance impact because it uses the IntersectionObserver API, which is highly optimized by browsers. It avoids expensive calculations on the main thread during scroll events. You can also use the maxConcurrent configuration option to limit how many animations can run at the same time.

Q: The animation on my full-screen hero section isn’t firing. What’s wrong?
A: This usually happens when an element is taller than the viewport. The default animation trigger threshold might never be met. The fix is to specify a lower threshold on the element. Try adding threshold-5 or threshold-10 to your data-usal attribute string. This will trigger the animation when just 5% or 10% of the element is visible.

Q: How does USAL.js handle performance with hundreds of animated elements on a single page?
A: USAL.js implements a concurrent animation limit through the maxConcurrent configuration option. By default, it limits simultaneous animations to prevent browser performance issues. You can adjust this value based on your target devices and performance requirements. The library also uses Intersection Observer for efficient visibility detection rather than scroll event listeners.

Q: What happens to USAL.js animations when users have reduced motion preferences enabled?
A: USAL.js respects the prefers-reduced-motion media query automatically. When users have motion reduction enabled, the library disables animations to provide an accessible experience. Elements still appear normally without the animated transitions.

Q: Is there a way to chain multiple USAL.js animations in sequence?
A: USAL.js animations are primarily designed for individual element transitions rather than complex sequences. You can achieve staggered effects using delay modifiers and split animations, but for complex animation timelines, GSAP or Framer Motion might be more suitable solutions.

Related Resources:

• 10 Best Scroll-triggered Animation Plugins With JavaScript

The post Tiny Framework-Agnostic Scroll Animation Library – USAL.js appeared first on CSS Script.