Convert Figma logo to code with AI

mciastek logosal

🚀 Performance focused, lightweight scroll animation library 🚀

3,593
178
3,593
41

Top Related Projects

26,486

Animate on scroll library

9,901

Reveal CSS animation as you scroll down a page

Animate elements as they scroll into view.

🛤 Detection of elements in viewport & smooth scrolling with parallax.

39,745

Most modern mobile touch slider with hardware accelerated transitions

Quick Overview

Sal is a lightweight JavaScript library for smooth scroll animations. It provides an easy way to implement scroll-based animations on web pages, allowing elements to animate as they enter or leave the viewport. Sal is designed to be performant and easy to use, with no dependencies.

Pros

  • Lightweight and performant, with a small file size
  • Easy to set up and use with minimal configuration
  • Supports various animation types and customization options
  • Works well with modern JavaScript frameworks and vanilla JS

Cons

  • Limited built-in animation options compared to more comprehensive libraries
  • May require additional CSS for more complex animations
  • Documentation could be more extensive, especially for advanced use cases
  • Lacks some features found in larger animation libraries

Code Examples

  1. Basic usage:
import sal from 'sal.js';

sal();

This initializes Sal with default options.

  1. Custom animation options:
sal({
  threshold: 0.5,
  once: false,
  animateClassName: 'custom-animate'
});

This sets a custom threshold, allows animations to repeat, and uses a custom animation class name.

  1. Using data attributes:
<div data-sal="slide-up" data-sal-delay="300" data-sal-easing="ease-out-bounce">
  Animated content
</div>

This applies a slide-up animation with a 300ms delay and custom easing.

Getting Started

  1. Install Sal:
npm install sal.js
  1. Import and initialize in your JavaScript file:
import sal from 'sal.js';
import 'sal.js/dist/sal.css';

sal();
  1. Add data attributes to HTML elements you want to animate:
<div data-sal="fade" data-sal-duration="500">
  This element will fade in when scrolled into view
</div>
  1. Customize animations using CSS if needed:
[data-sal|='fade'] {
  opacity: 0;
  transition: opacity 0.3s;
}
[data-sal|='fade'].sal-animate {
  opacity: 1;
}

Competitor Comparisons

26,486

Animate on scroll library

Pros of AOS

  • More popular and widely used (30k+ stars vs 1k+ for SAL)
  • Supports a wider range of animation effects out-of-the-box
  • Better documentation and examples

Cons of AOS

  • Larger file size (14KB vs 3KB for SAL)
  • More complex configuration options may be overwhelming for simple use cases

Code Comparison

SAL:

sal({
  threshold: 0.5,
  once: false,
});

AOS:

AOS.init({
  offset: 200,
  duration: 600,
  easing: 'ease-in-sine',
  delay: 100,
});

Both libraries use similar initialization patterns, but AOS offers more configuration options by default. SAL's approach is simpler and more straightforward, while AOS provides greater flexibility for complex animations.

SAL focuses on revealing elements as they enter the viewport, while AOS offers a broader range of animation types and triggers. AOS is better suited for projects requiring diverse animations, whereas SAL is ideal for simpler scroll-based reveal effects with a smaller footprint.

9,901

Reveal CSS animation as you scroll down a page

Pros of WOW

  • Lightweight and simple to use with minimal configuration required
  • Supports a wider range of browsers, including older versions of IE
  • Offers more animation options out of the box

Cons of WOW

  • Less actively maintained, with fewer recent updates
  • Limited customization options compared to Sal
  • Lacks advanced features like custom CSS properties for animations

Code Comparison

WOW:

new WOW().init();

<div class="wow fadeIn" data-wow-duration="2s" data-wow-delay="1s">
  Animated content
</div>

Sal:

sal();

<div data-sal="fade" data-sal-duration="1000" data-sal-delay="300">
  Animated content
</div>

Both libraries use similar approaches for initializing animations and applying them to elements. WOW uses class-based selectors, while Sal uses data attributes. Sal's syntax is slightly more modern and readable.

WOW is a simpler option for basic scroll animations, especially if you need to support older browsers. However, Sal offers more flexibility and customization options, making it a better choice for projects requiring advanced animations or fine-tuned control over the animation process.

Animate elements as they scroll into view.

Pros of ScrollReveal

  • More mature and widely adopted project with 21.5k+ stars on GitHub
  • Extensive documentation and examples available
  • Supports both JavaScript and CSS-based animations

Cons of ScrollReveal

  • Larger file size (17KB minified and gzipped)
  • More complex API with a steeper learning curve
  • Limited to scroll-based animations only

Code Comparison

ScrollReveal:

ScrollReveal().reveal('.headline', {
    delay: 500,
    distance: '50px',
    origin: 'bottom',
    duration: 1000
});

Sal:

sal({
    threshold: 0.5,
    once: false,
    animateClassName: 'sal-animate'
});

Key Differences

  • Sal is lightweight (2.4KB gzipped) compared to ScrollReveal
  • Sal uses a simpler API with data attributes for configuration
  • ScrollReveal offers more advanced animation options and customization
  • Sal supports IntersectionObserver for better performance on modern browsers
  • ScrollReveal has a larger community and more frequent updates

Both libraries provide scroll-based animations, but they cater to different needs. Sal is ideal for simple, lightweight implementations, while ScrollReveal offers more advanced features and broader browser support at the cost of increased complexity and file size.

🛤 Detection of elements in viewport & smooth scrolling with parallax.

Pros of Locomotive Scroll

  • More comprehensive scrolling library with advanced features like smooth scrolling and parallax effects
  • Active development with frequent updates and a larger community
  • Better documentation and examples for easier implementation

Cons of Locomotive Scroll

  • Larger file size and potentially higher performance overhead
  • Steeper learning curve due to more complex API and configuration options
  • May be overkill for simple scroll animations

Code Comparison

Sal:

sal({
  threshold: 0.5,
  once: false,
});

Locomotive Scroll:

const scroll = new LocomotiveScroll({
  el: document.querySelector('[data-scroll-container]'),
  smooth: true,
  multiplier: 1,
});

Summary

Locomotive Scroll offers more advanced features and active development, making it suitable for complex scrolling effects and modern web applications. However, it comes with a larger footprint and steeper learning curve. Sal, on the other hand, is simpler and lighter, focusing primarily on scroll-based animations. The choice between the two depends on the project's specific requirements and complexity.

39,745

Most modern mobile touch slider with hardware accelerated transitions

Pros of Swiper

  • More comprehensive and feature-rich slider/carousel solution
  • Supports touch swiping on mobile devices
  • Extensive documentation and active community support

Cons of Swiper

  • Larger file size and potentially higher performance overhead
  • Steeper learning curve due to more complex API and options

Code Comparison

Sal (Scroll Animation Library):

sal({
  threshold: 0.5,
  once: false,
});

Swiper:

const swiper = new Swiper('.swiper-container', {
  slidesPerView: 3,
  spaceBetween: 30,
  pagination: {
    el: '.swiper-pagination',
    clickable: true,
  },
});

Summary

Sal is a lightweight scroll animation library, while Swiper is a full-featured slider/carousel solution. Sal focuses on adding animations to elements as they enter the viewport, whereas Swiper provides interactive sliding functionality for content. Swiper offers more advanced features and customization options but comes with a larger file size and potentially more complex implementation. Sal is simpler to use for basic scroll animations but lacks the extensive slider capabilities of Swiper. The choice between the two depends on the specific project requirements and whether advanced slider functionality is needed.

Convert Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Sal npm version License: MIT Build Status

Performance focused, lightweight (less than 2.8 kb) scroll animation library, written in vanilla JavaScript. No dependencies!

Sal (Scroll Animation Library) was created to provide a performant and lightweight solution for animating elements on scroll. It's based on the Intersection Observer, which gives amazing performance in terms of checking the element's presence in the viewport.

Note: Intersection Observer API is an experimental technology so be sure to consult the browser compatibility table and consider using a polyfill.

Table of Contents

Install

# Usage with NPM
$ npm install --save sal.js

# and with Yarn
$ yarn add sal.js

Load it with your favorite module loader or use as a global variable

// ES6 modules
import sal from 'sal.js'

// CommonJS modules
var sal = require('sal.js')

And remember to add styles

// Webpack
@import '~sal.js/sal.css';

// Other
@import './node_modules/sal.js/dist/sal.css';

Usage

In HTML, add a data-sal attribute with the animation name as value, e.g.:

<div data-sal="fade"></div>

Then simply initialize Sal in your script file:

sal();

It will look for all elements with a data-sal attribute and launch their animation when in viewport.

Animations

In sal.js you can easily change animation's options, by adding a proper data attribute:

  • data-sal-duration - changes duration of the animation (from 200 to 2000 ms)
  • data-sal-delay - adds delay to the animation (from 5 to 1000 ms)
  • data-sal-easing - sets easing for the animation (see easings.net for reference)

For example:

<div
  data-sal="slide-up"
  data-sal-delay="300"
  data-sal-easing="ease-out-back"
></div>

The library supports several animations:

  • fade
  • slide-up
  • slide-down
  • slide-left
  • slide-right
  • zoom-in
  • zoom-out
  • flip-up
  • flip-down
  • flip-left
  • flip-right

Duration and delay

Additionaly, when you want to customise animation's properties - duration, delay and easing, you can use CSS variables to set any value you want. See the following example:

<div
  data-sal="slide-up"
  style="--sal-duration: 3s; --sal-delay: 2s;"
></div>

Supported custom properties:

  • --sal-duration
  • --sal-delay
  • --sal-easing

Remember, that you can use only data attributes (e.g. data-sal-delay) or CSS custom properties (e.g. --sal-delay). Data attributes have precedence over CSS custom properties.

Repeating animation

By default every animation is played once. You can change it by setting once option to false (see Options). What's more, it's possible to override this option for an animated element by adding one of the following attributes:

  • data-sal-repeat - forces animation replay
  • data-sal-once - plays animation once

Options

PropertyTypeDescriptionDefault
thresholdNumberPercentage of an element's area that needs to be visible to launch animation (see docs)0.5
onceBooleanDefines if animation needs to be launched once. Can be overridden, see Repeating Animation.true
disabledBoolean or FunctionFlag (or a function returning boolean) for disabling animationsfalse

You can set options during Sal's initialization, e.g.:

sal({
  threshold: 1,
  once: false,
});

Advanced options

PropertyTypeDescriptionDefault
rootElement or nullThe element that is used as the viewport for checking visibility of the target (see docs)window
selectorStringSelector of the elements to be animated[data-sal]
animateClassNameStringClass name which triggers animationsal-animate
disabledClassNameStringClass name which defines the disabled statesal-disabled
rootMarginStringCorresponds to root's bounding box margin (see docs)0% 50%
enterEventNameStringEnter event name (see Events)sal:in
exitEventNameStringExit event name (see Events)sal:out

API

Method nameDescription
enableEnables animations
disableDisables animations
resetResets instance and allows to pass new options (see Options)
updateUpdates observer with new elements to animated. Useful for dynamically injected HTML.

Public methods are available after Sal's initialization:

const scrollAnimations = sal();

scrollAnimations.disable();

Changing options after intialization

If you want to change Sal's options once it's been initialized, you should use reset method, that allows you to pass new set of options. It can be useful, when you would like to provide different options for specific viewport sizes.

const scrollAnimations = sal();

// Provide new options
scrollAnimations.reset({
  selector: 'animated-element',
  once: true,
});

Events

This library supports events, fired when element is entering or exiting viewport (they are named sal:in and sal:out by default). Property detail is IntersectionObserverEntry object.

You can attach listener to specific element.

// Get element with ".animated" class, which has "data-sal" attribute
const element = document.querySelector('.animated');

element.addEventListener('sal:in', ({ detail }) => {
  console.log('entering', detail.target);
});

or to the whole document

document.addEventListener('sal:out', ({ detail }) => {
  console.log('exiting', detail.target);
});

Note: This library uses Custom Event to trigger events on animated elements. Check the compatibility table to know if your browser supports it and use a polyfill if needed.

Misc

No-JS support

If you aim to support users that don't allow sites to use JavaScript, you should consider disabling animations' styles in the first place. You can use <noscript /> element to inject required CSS. Here's an example:

<noscript>
  <style type="text/css">
    [data-sal|='fade'] {
      opacity: 1;
    }

    [data-sal|='slide'],
    [data-sal|='zoom'] {
      opacity: 1;
      transform: none;
    }

    [data-sal|='flip'] {
      transform: none;
    }
  </style>
</noscript>

License

Created by Mirek Ciastek. Released under the MIT License.

NPM DownloadsLast 30 Days