Package Exports

scrollcue.js
scrollcue.js/scrollcue.all-in-one.min.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (scrollcue.js) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

ScrollCue.js

A lightweight JavaScript scroll animation library using the Intersection Observer API. ScrollCue.js animates elements when they enter the viewport, with configurable animations, delays, and durations. Now with buttery-smooth advanced animations while remaining dependency-free!

Features

Dependency-free (no jQuery required)
Lightweight
Uses modern Intersection Observer API
Multiple animation types with buttery-smooth transitions
Physics-based animations for natural movement
Advanced easing functions for natural motion
Staggered animations for groups of elements
Timeline sequencing for complex animations
Scroll-linked animations and progress tracking
Transform origin controls and 3D perspective
Works automatically when included (like particles.js)
Can be used directly from CDN - no downloads needed
One-line implementation available (JS + CSS together)

See all the features here!

Installation

One-Line Implementation (Recommended)

The simplest way to use ScrollCue.js is with the all-in-one version that includes both JS and CSS in a single file:

<!-- From npm -->
<script src="https://cdn.jsdelivr.net/npm/scrollcue.js@latest/scrollcue.all-in-one.min.js"></script>
<!-- Or -->
<script src="https://unpkg.com/scrollcue.js@latest/scrollcue.all-in-one.min.js"></script>

Direct Download

Or download the files from this repository and include them in your project:

<script src="path/to/scrollcue.all-in-one.js"></script>

That's it! No initialization code needed. ScrollCue.js automatically detects elements with the scrollcue class and sets up animations when the page loads.

Usage

Add the scrollcue class to any element you want to animate when scrolled into view.
Add a data-cue attribute to specify the animation type.
Optionally add data-delay and data-duration attributes for timing control.

<div class="scrollcue" data-cue="fade-in">
  This element will fade in when scrolled into view.
</div>

<div class="scrollcue" data-cue="slide-up" data-delay="200" data-duration="1000">
  This element will slide up with a 200ms delay and 1000ms duration.
</div>

Available Animations

Basic Animations

fade-in: Simple fade-in effect
slide-up: Slides up from below with physics-based momentum
slide-down: Slides down from above with physics-based momentum
slide-left: Slides in from the right with smooth deceleration
slide-right: Slides in from the left with smooth deceleration
zoom-in: Scales up from smaller size with slight overshoot
zoom-out: Scales down from larger size with spring-like motion
rotate-in: Rotates and fades in with natural damping
flip-in: Flips in with realistic 3D physics
bounce-in: Bounces in with enhanced elastic effect
spring: Spring-physics animation with natural oscillation
elastic-in: Elastic animation with spring-like oscillation
flip-3d: Advanced 3D flip with perspective and rotation

Special Effects

wave: Gentle wave-like motion with improved physics
float: Smooth floating animation with subtle rotation
wind: Wind sweeping effect with natural movement
ripple: Water ripple effect with radial expansion
boat-rock: Realistic boat rocking motion
storm: Dynamic storm-like shaking
breaking-wave: Natural wave breaking motion
typing: Type text with cursor blink effect
shake: Quick shake animation with physics-based damping
flicker: Light flickering effect with brightness
stagger: Animate child elements in sequence with configurable delays

Example Usage

Basic animations:

<div class="scrollcue" data-cue="fade-in">
  This element will fade in when scrolled into view.
</div>

<div class="scrollcue" data-cue="slide-up" data-delay="200" data-duration="1000">
  This element will slide up with a 200ms delay and 1000ms duration.
</div>

Special effects:

<!-- Ocean-themed effects -->
<div class="scrollcue" data-cue="wave">
  Wave motion effect
</div>

<div class="scrollcue" data-cue="boat-rock">
  ⛵ Boat rocking animation
</div>

<div class="scrollcue" data-cue="ripple">
  💧 Ripple effect
</div>

<!-- Stagger animation -->
<div class="scrollcue" data-cue="stagger" data-stagger="100">
  <div>First item</div>
  <div>Second item</div>
  <div>Third item</div>
</div>

JavaScript API

ScrollCue.js initializes automatically when included - no manual initialization required. However, you can control it with JavaScript if needed:

// Access the global instance
window.scrollCue

// Manual refresh to detect new elements
scrollCue.refresh();

// Destroy instance
scrollCue.destroy();

// Create a new instance with custom options
const myScrollCue = new ScrollCue({
  rootMargin: '0px',
  threshold: 0.2,
  duration: 800,
  delay: 0,
  easing: 'cubic-bezier(0.25, 0.1, 0.25, 1.0)',
  once: true,
  useRAF: true,       // Use requestAnimationFrame for smoother animations
  stagger: 150        // Default stagger delay for child elements
});
myScrollCue.init();

// Advanced Timeline functionality
const timeline = scrollCue.timeline()
  .add('#first-element', {cue: 'fade-in', delay: 0})
  .add('#second-element', {cue: 'slide-up', position: '+=200'})
  .add('#third-element', {cue: 'zoom-in', position: '<'});

timeline.play();

// Create staggered animations
scrollCue.sequence('#container')
  .add('.item', {cue: 'fade-in', stagger: 100})
  .play();

// Register custom easing functions
scrollCue.registerEasing('customBounce', 'cubic-bezier(0.175, 0.885, 0.32, 1.275)');

// Create scroll-linked animations
scrollCue.scrollTween('.parallax-element', {
  start: 'top bottom',  // When element top reaches bottom of viewport
  end: 'bottom top',    // When element bottom reaches top of viewport
  properties: {
    y: {from: 0, to: -100, unit: 'px'},
    opacity: {from: 0, to: 1},
    scale: {from: 0.8, to: 1}
  }
});

// Add custom animations
scrollCue.addAnimation('custom-animation', {
  initial: 'transform: rotate(45deg); opacity: 0;',
  visible: 'transform: rotate(0); opacity: 1;',
  keyframes: `
    0% { transform: rotate(45deg); opacity: 0; }
    100% { transform: rotate(0); opacity: 1; }
  `
});

Options

Option	Type	Default	Description
rootMargin	String	'0px'	Margin around the root. See Intersection Observer API.
threshold	Number	0.2	Percentage of element visibility needed to trigger animation.
duration	Number	800	Default animation duration in milliseconds.
delay	Number	0	Default delay before animation starts in milliseconds.
easing	String	'cubic-bezier(0.25, 0.1, 0.25, 1.0)'	CSS timing function for animations.
once	Boolean	true	Whether to animate elements only once or every time they enter the viewport.
useRAF	Boolean	true	Whether to use requestAnimationFrame for smoother animations.
stagger	Number	0	Default stagger delay for child elements in milliseconds.
ease	String	'cubic-bezier(0.25, 0.1, 0.25, 1.0)'	Alias for easing (compatible naming).

Browser Support

ScrollCue.js works in all modern browsers that support the Intersection Observer API (Chrome, Firefox, Safari, Edge). A fallback is provided for older browsers, which will simply display all elements without animation.

License

MIT License

Contributing

If you're interested in contributing to ScrollCue.js, please check out the CONTRIBUTING.md file for guidelines.

Important: Don't edit the all-in-one files directly. Make changes to the separate scrollcue.js and scrollcue.css files, then generate the combined version as described in the contributing guide.

Star this repository if you found it helpful! It'd help me a lot.

scrollcue.js