ScrollJs: Animate-on-Scroll JavaScript Library 🌊

A lightweight JavaScript library to trigger animations and effects when elements scroll into view. Control your animations with custom CSS or built-in classes! ✨

⚠️ Warning: Do not use v2.0.0

A critical bug in version v2.0.0 prevents built-in animations from working correctly.
Please upgrade to v2.0.1 or later for a stable experience.
If you're referencing v2.0.0 in your documentation, consider updating to reference latest or v2.0.1 instead.

Project Overview

ScrollJs is designed to be easy to use, flexible, and performant. It provides a simple API to observe elements and trigger animations as users scroll down the page. Unlike other libraries, ScrollJs allows you to leverage your own CSS animation classes, giving you full control over animation styles.

Installation

Get started by installing ScrollJs using npm or yarn:

git clone git@github.com:Charmingdc/ScrollJs.git

Via NPM

npm install @charmingdc/scrolljs

Via Yarn

yarn add @charmingdc/scrolljs

Or, include it directly from a CDN:

<link rel="stylesheet" href="dist/scrolljs.css">
<script src="dist/scroll.umd.js"></script>

Usage

Basic Setup

1. Import: Import ScrollObserver into your project.

   import ScrollObserver from '@charmingdc/scrolljs';

2. Initialize: Create a new ScrollObserver instance.

   const observer = new ScrollObserver();

3. Observe Elements: Use the .observe() method to start tracking elements.

   const element = document.querySelector('.my-element');
   observer.observe(element, null, 'fade-in-up');

Options

Customize ScrollJs with the following options:

Click to expand options

• animateOnce: Animate elements only once.
• root: Specify a container for scroll observation.
• threshold: Percentage of element visibility to trigger animation.
• rootMargin: Margin around the root element.

Examples

Here's a simple example of using ScrollJs with a fade-in animation:

<div class="my-element scrolljs-hidden scrolljs-fade-in-up">
  <h2>Hello ScrollJs!</h2>
  <p>This element will fade in as you scroll.</p>
</div>

const observer = new ScrollObserver();
const element = document.querySelector('.my-element');
observer.observe(element, null, 'scrolljs-fade-in-up');

For more detailed usage, check the Documentation.

Features

• ✨ Lightweight: Minimal footprint with no dependencies.
• 🎨 Customizable: Use your own CSS animations.
• 🔩 Easy to Use: Simple API with straightforward implementation.
• 🔄 Animate Once: Option to trigger animations only once.
• 🌱 Lazy Load Images: Load images only when they come into view.
• 🎛️ Observer Options: Customizable root, threshold, and margin settings.

Technologies Used

Technology	Description	Documentation
JavaScript	Core language for the library	MDN Web Docs
Intersection Observer API	Used for detecting element visibility	MDN Web Docs
Rollup	Module bundler	Rollup.js
Docusaurus	Documentation tool	Docusaurus
CSS	Styling animations	MDN Web Docs

Contributing

Contributions are welcome! Follow these steps to contribute:

• 🍴 Fork the repository.
• 🌿 Create a new branch for your feature or bug fix.
• 💻 Make your changes and commit them with descriptive commit messages.
• 🚀 Submit a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Adebayo Muis (Charmingdc) - https://twitter.com/Charmingdc01