Sal
![Build Status](https://travis-ci.com/mciastek/sal.svg?branch=master)
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
$ npm install --save sal.js
$ yarn add sal.js
Load it with your favorite module loader or use as a global variable
import sal from 'sal.js'
var sal = require('sal.js')
And remember to add styles
@import '~sal.js/sal.css';
@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 replaydata-sal-once
- plays animation once
Options
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.:
sal({
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 |
API
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();
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();
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.
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.