Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mciastek/sal

🚀 Performance focused, lightweight scroll animation library 🚀
https://github.com/mciastek/sal

Last synced: 3 months ago
JSON representation

🚀 Performance focused, lightweight scroll animation library 🚀

Lists

README 

        
# 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 `` element to inject required CSS. Here's an example:



```html



  

    [data-sal|='fade'] {

      opacity: 1;

    }



    [data-sal|='slide'],

    [data-sal|='zoom'] {

      opacity: 1;

      transform: none;

    }



    [data-sal|='flip'] {

      transform: none;

    }

  



```



## License



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