# Sal [![npm version](https://badge.fury.io/js/sal.js.svg)](https://www.npmjs.com/package/sal.js) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/mciastek/sal/blob/master/LICENSE) [![Build Status](https://travis-ci.com/mciastek/sal.svg?branch=master)](https://travis-ci.com/mciastek/sal) 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](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API), 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](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API#Browser_compatibility) and consider using a [polyfill](https://github.com/w3c/IntersectionObserver/tree/master/polyfill). ## Table of Contents - [Install](#install) - [Usage](#usage) - [Animations](#animations) - [Options](#options) - [API](#api) - [Events](#events) - [Misc](#misc) - [License](#license) ## Install ```sh # 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 ```js // ES6 modules import sal from 'sal.js' // CommonJS modules var sal = require('sal.js') ``` And remember to add styles ```scss // 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.: ```html

``` Then simply initialize Sal in your script file: ```js 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](https://easings.net/) for reference) For example: ```html

``` 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](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) to set any value you want. See the following example: ```html

``` 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](#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 | Property | Type | Description | Default | |---------------------------|-------------|---------------|---------| | `threshold` | Number | Percentage of an element's area that needs to be visible to launch animation (see [docs](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/thresholds)) | `0.5` | | `once` | Boolean | Defines if animation needs to be launched once. Can be overridden, see [Repeating Animation](#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.: ```js 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](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/root)) | `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](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/rootMargin)) | `0% 50%` | | `enterEventName` | String | Enter event name (see [Events](#events)) | `sal:in` | | `exitEventName` | String | Exit event name (see [Events](#events)) | `sal:out` | ## API | Method name | Description | |---------------------------|-------------| | `enable` | Enables animations | | `disable` | Disables animations | | `reset` | Resets instance and allows to pass new options (see [Options](#options)) | | `update` | Updates observer with new elements to animated. Useful for dynamically injected HTML. | Public methods are available after Sal's initialization: ```js 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. ```js 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](https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserverEntry) object. You can attach listener to specific element. ```js // 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 ```js document.addEventListener('sal:out', ({ detail }) => { console.log('exiting', detail.target); }); ``` **Note:** This library uses [Custom Event](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) to trigger events on animated elements. Check the [compatibility table](https://caniuse.com/#search=custom%20event) to know if your browser supports it and use a [polyfill](https://github.com/kumarharsh/custom-event-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 `

``` ## License Created by [Mirek Ciastek](https://github.com/mciastek). Released under the [MIT License](https://github.com/mciastek/sal/blob/master/LICENSE).

	Stars	Issues	Version	Updated	Created
sal.js	3,552	40	0.8.5	3 years ago	7 years ago
scroll-behavior	545	38	0.11.0	4 years ago	8 years ago
scrollmagic			2.0.8	3 years ago	9 years ago
scrolltrigger-classes	3,931	6	0.3.6	7 years ago	8 years ago

sal.js vs scroll-behavior vs scrollmagic vs scrolltrigger-classes

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Popular Searches

Sick of boring JavaScript newsletters?

Downloads in past