scrollq

ScrollQ

Lightweight, dependency-free scroll animations using the Intersection Observer API. Simple, performant, and highly customizable.

Features

• 🪶 Lightweight - 1.6KB JS + 1.5KB CSS minified
• ⚡ Performant - Native Intersection Observer API
• 🎨 Flexible - 10 animation variants with full customization
• ♿ Accessible - Respects prefers-reduced-motion

Installation

npm install scrollq

Quick Start

<link rel="stylesheet" href="node_modules/scrollq/dist/scrollQ.min.css" />
<script type="module">
  import { initScrollQ } from "scrollq";
  initScrollQ();
</script>

<!-- Add animations -->
<div data-q="fade-up">Animates on scroll</div>
<div data-q="slide-left" data-q-delay="200">Delayed animation</div>

Global Configuration

initScrollQ({
  threshold: 0.5, // When element is 50% visible (0-1)
  reverse: false, // Enable reverse animations
  rootMargin: "-50px", // Offset trigger area
  duration: "0.6s", // Default animation duration
  easing: "ease-out", // Default timing function
  fromY: "7rem", // Default vertical distance
  fromX: "7rem", // Default horizontal distance
  selector: "[data-q]", // Custom selector
});

Cleanup (SPAs)

Option 1: Cleanup specific instance

const cleanup = initScrollQ();
// Later, when component unmounts:
cleanup();

Option 2: Cleanup all instances globally

import { initScrollQ, destroyScrollQ } from "scrollq";

initScrollQ();
// Later, to clean up everything:
destroyScrollQ();

Animations

Type	Description
fade	Simple fade in
fade-up	Fade in from below
fade-down	Fade in from above
fade-left	Fade in from right
fade-right	Fade in from left
scale	Fade + scale up
slide-up	Slide from below (no fade)
slide-down	Slide from above (no fade)
slide-left	Slide from right (no fade)
slide-right	Slide from left (no fade)

Customization

Element Attributes

Attribute	Default	Description
data-q	-	Animation type (required)
data-q-threshold	0.5	Trigger visibility (0.0-1.0)
data-q-offset	-	Viewport offset (%, px, vh, rem)
data-q-from	7rem	Animation distance
data-q-duration	0.6s	Animation duration
data-q-easing	ease-out	Timing function
data-q-delay	-	Delay in milliseconds
data-q-reverse	false	Reverse on scroll up

CSS Variables

:root {
  --q-duration: 0.8s;
  --q-easing: cubic-bezier(0.4, 0, 0.2, 1);
  --q-from-y: 5rem;
  --q-from-x: 5rem;
}

Examples

Staggered list:

<ul>
  <li data-q="fade-up" data-q-delay="100">First</li>
  <li data-q="fade-up" data-q-delay="200">Second</li>
  <li data-q="fade-up" data-q-delay="300">Third</li>
</ul>

Trigger at viewport middle:

<div data-q="fade-up" data-q-offset="-50%">Centered trigger</div>

Reverse animations:

<div data-q="scale" data-q-reverse>Reverses when scrolling up</div>

Custom animation:

<div data-q="fade-up" data-q-from="10rem" data-q-duration="1s" data-q-easing="ease-in-out">
  Smooth long-distance fade
</div>

How It Works

ScrollQ uses the Intersection Observer API to watch elements. When visible, it adds the q-active class to trigger CSS transitions.

Behavior:

• Animations trigger when scrolling down and element enters from bottom
• With data-q-reverse, animations reverse when scrolling up
• Elements already scrolled past are automatically activated on page load
• Respects prefers-reduced-motion for accessibility

Browser Support

Chrome 51+, Firefox 55+, Safari 12.1+, Edge 15+

Development

npm install
npm run build  # Builds dist files

File sizes: 1.6KB JS + 1.5KB CSS (minified)

License

MIT License - feel free to use in personal and commercial projects.

Credits

Created by Kevin Terry

Inspired by AOS and the need for a super simple, modern scroll animation solution.