Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time
February 13, 2021 17:47
February 13, 2021 17:47
September 8, 2019 14:11
September 27, 2017 22:36
September 8, 2019 14:11
September 8, 2019 14:11
October 24, 2020 16:29
October 24, 2020 16:49
September 27, 2017 22:36
March 21, 2021 12:35
February 13, 2021 17:47
May 1, 2021 18:37

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


# 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';


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:


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


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 for reference)

For example:


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:

  style="--sal-duration: 3s; --sal-delay: 2s;"

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


Property Type Description Default
threshold Number Percentage of an element's area that needs to be visible to launch animation (see docs) 0.5
once Boolean Defines if animation needs to be launched once. Can be overridden, see Repeating Animation. true
disabled Boolean or Function Flag (or a function returning boolean) for disabling animations false

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

  threshold: 1,
  once: false,

Advanced options

Property Type Description Default
root Element or null The element that is used as the viewport for checking visibility of the target (see docs) window
selector String Selector of the elements to be animated [data-sal]
animateClassName String Class name which triggers animation sal-animate
disabledClassName String Class name which defines the disabled state sal-disabled
rootMargin String Corresponds to root's bounding box margin (see docs) 0% 50%
enterEventName String Enter event name (see Events) sal:in
exitEventName String Exit event name (see Events) sal:out


Method name Description
enable Enables animations
disable Disables animations
reset Resets instance and allows to pass new options (see Options)
update Updates observer with new elements to animated. Useful for dynamically injected HTML.

Public methods are available after Sal's initialization:

const scrollAnimations = sal();


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
  selector: 'animated-element',
  once: true,


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 }) => {

or to the whole document

document.addEventListener('sal:out', ({ detail }) => {

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.


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:

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

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

    [data-sal|='flip'] {
      transform: none;


Created by Mirek Ciastek. Released under the MIT License.