@proto-cool/cascade

v1.0.3

Published

7 months ago

A lightweight TypeScript library for easily defining smooth, performant animations when elements enter the viewport.

@proto-cool/cascade

A lightweight TypeScript library for easily defining smooth, performant animations when elements enter the viewport.

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

# Using pnpm (recommended)
pnpm add @proto-cool/cascade

# Using npm
npm install @proto-cool/cascade

# Using yarn
yarn add @proto-cool/cascade

Quick Start

Import and enable the library:

//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();

Add the data attribute to any HTML element:

<!-- Basic fade animation when element enters viewport -->
<div data-cascade="fadeIn">I'll fade in when visible</div>

<!-- Slide animation with custom delay -->
<div data-cascade="fadeInUp" data-cascade-delay="0.5">
    I'll fade in, sliding upwards, after a delay of half a second
</div>

Add noscript fallback for accessibility:

Add this to your HTML <head> for users with JavaScript disabled:

<!-- Copy this noscript tag to your head section -->
<noscript>
    <style>
        /* Show all elements with data-cascade attribute when JS is disabled */
        [data-cascade] {
            opacity: 1 !important;
        }
    </style>
</noscript>

<!-- Or use the provided noscript string: -->
<head>
    <!-- your other head content -->
    <script>
        document.write(cascade.noscript);
    </script>
</head>

Configuration

Global Configuration

Customize the default behavior for all animations:

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:

<div
    data-cascade="bounceIn"
    data-cascade-duration="1.2"
    data-cascade-delay="0.3"
    data-cascade-bounce="0.4"
    data-cascade-ease="easeInOut"
>
    Customized animation
</div>

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:

<div data-cascade="fadeIn">Fade in</div>
<div data-cascade="fadeInZoom">Zoom in</div>
<div data-cascade="FadeInUp">Slide up in</div>
<div data-cascade="flipIn">Flip in</div>
<div data-cascade="bounceIn">Bounce in</div>

Advanced Usage

Custom Intersection Margins

Adjust when animations trigger relative to the viewport:

<!-- Animation starts when element is 100px away from entering viewport -->
<div data-cascade="fadeIn" data-cascade-margin="100px"></div>

<!-- Different margins for each side (top, right, bottom, left) -->
<div data-cascade="fadeIn" data-cascade-margin="50px 0px 0px 0px"></div>

Animation Amount Threshold

Control how much of the element must be visible to trigger the animation:

<!-- Trigger when 50% of element is visible -->
<div data-cascade="fadeIn" data-cascade-amount="0.5"></div>

<!-- Trigger when any part of element is visible -->
<div data-cascade="fadeIn" data-cascade-amount="some"></div>

<!-- Trigger when element is fully visible -->
<div data-cascade="FadeIn" data-cascade-amount="all"></div>

Custom Animation Physics

Fine-tune spring animations with custom physics parameters:

<!-- Extra bouncy spring animation -->
<div
    data-cascade="bounceIn"
    data-cascade-bounce="0.8"
    data-cascade-stiffness="200"
    data-cascade-damping="5"
>
    Bouncy content
</div>

Browser Support

Cascade works in all modern browsers that support the Intersection Observer API (Chrome, Firefox, Safari, Edge).

Development

# 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:

import cascade from "@proto-cool/cascade";
import type { AnimationOptions } from "@proto-cool/cascade";

const options: Partial<AnimationOptions> = {
    duration: 1.2,
    type: "spring",
    bounce: 0.3,
};

cascade.enable(options);

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@proto-cool/cascade

Features

Installation

Quick Start

Configuration

Global Configuration

Per-Element Configuration

Available Animations

Advanced Usage

Custom Intersection Margins

Animation Amount Threshold

Custom Animation Physics

Browser Support

Development

TypeScript Support

License