# @proto-cool/cascade A lightweight TypeScript library for easily defining smooth, performant animations when elements enter the viewport. [![npm version](https://img.shields.io/npm/v/@proto-cool/cascade.svg)](https://www.npmjs.com/package/@proto-cool/cascade) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) ## Features - 🚀 **Zero Configuration** - Add a single data attribute to any element and it animates when scrolled into view - ⚡ **Performant** - Built on the Motion animation library with optimized viewport detection - 🎨 **Versatile** - Multiple animation types including fade, slide, scale, and custom spring physics - 🔧 **Customizable** - Configure animations globally or per-element using data attributes - 📱 **Responsive** - Works perfectly across all device sizes - ♿ **Accessible** - Includes fallbacks for users with JavaScript disabled - 🧩 **Modular** - Use only what you need, minimal bundle size ## Installation ```bash # Using pnpm (recommended) pnpm add @proto-cool/cascade # Using npm npm install @proto-cool/cascade # Using yarn yarn add @proto-cool/cascade ``` ## Quick Start 1. **Import and enable the library:** ```javascript //Import the CSS to have items invisible by default import "@proto-cool/cascade/cascade.css"; // Import the `cascade` object for access to enable() and noscript import cascade from "@proto-cool/cascade"; // Initialize Cascade with default settings cascade.enable(); ``` 2. **Add the data attribute to any HTML element:** ```html

I'll fade in when visible

I'll fade in, sliding upwards, after a delay of half a second

``` 3. **Add noscript fallback for accessibility:** Add this to your HTML `` for users with JavaScript disabled: ```html ``` ## Configuration ### Global Configuration Customize the default behavior for all animations: ```javascript cascade.enable({ // Animation timing defaults duration: 0.8, // Animation duration in seconds delay: 0, // Delay before animation starts // Animation type default type: "spring", // 'spring' | 'tween' | 'keyframes' | 'decay' | 'inertia' // Intersection observer defaults margin: "0px", // Root margin (e.g. '50px' or '10% 20px') amount: 0.2, // Trigger when 20% visible (0-1, 'some', or 'all') // Spring physics defaults (when type = 'spring') bounce: 0.25, // Spring bounciness damping: 10, // Spring damping stiffness: 100, // Spring stiffness // Tween easing defaults (when type = 'tween') ease: "easeInOut", // Easing function // Animation repeat defaults repeat: 0, // Number of repeats (0 = no repeat) repeatType: "loop", // 'loop' | 'reverse' | 'mirror' repeatDelay: 0, // Delay between repeats }); ``` ### Per-Element Configuration Override settings on individual elements using data attributes: ```html

Customized animation

``` ## Available Animations This package offers a variety of ready-to-use animation presets designed for common UI effects. Below is a summary of each animation and what it does: | Name | Description | | ------------ | ------------------------------------------------------- | | fadeIn | Fades in an element from transparent to visible. | | fadeInZoom | Fades in while zooming in from 80% to full size. | | fadeInUp | Fades in while moving upward into place. | | fadeInDown | Fades in while moving downward into place. | | fadeInLeft | Fades in while moving in from the right. | | fadeInRight | Fades in while moving in from the left. | | fadeOut | Fades out an element from visible to transparent. | | fadeOutZoom | Fades out while shrinking (zooming out to 70%). | | fadeOutUp | Fades out while moving upward out of view. | | fadeOutDown | Fades out while moving downward out of view. | | fadeOutLeft | Fades out while moving leftward out of view. | | fadeOutRight | Fades out while moving rightward out of view. | | bounceIn | Bounces in, scaling up and settling to full size. | | bounceOut | Bounces out, expanding slightly then shrinking away. | | flipIn | Flips in along the Y axis, rotating from 90° to 0°. | | flipOut | Flips out along the Y axis, rotating from 0° to 90°. | | rotateIn | Rotates in, spinning from -180° to 0° while fading in. | | rotateOut | Rotates out, spinning from 0° to 180° while fading out. | Example usage: ```html

Fade in

Zoom in

Slide up in

Flip in

Bounce in

``` ## Advanced Usage ### Custom Intersection Margins Adjust when animations trigger relative to the viewport: ```html

``` ### Animation Amount Threshold Control how much of the element must be visible to trigger the animation: ```html

``` ### Custom Animation Physics Fine-tune spring animations with custom physics parameters: ```html

Bouncy content

``` ## Browser Support Cascade works in all modern browsers that support the Intersection Observer API (Chrome, Firefox, Safari, Edge). ## Development ```bash # Install dependencies pnpm install # Build the library pnpm run build # Format code with Prettier pnpm run format ``` ## TypeScript Support Cascade is written in TypeScript and includes full type definitions: ```typescript import cascade from "@proto-cool/cascade"; import type { AnimationOptions } from "@proto-cool/cascade"; const options: Partial = { duration: 1.2, type: "spring", bounce: 0.3, }; cascade.enable(options); ``` ## License MIT © [protocol7](https://github.com/proto-cool)