Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://mciastek.github.io/sal/
🚀 Performance focused, lightweight scroll animation library 🚀
https://mciastek.github.io/sal/
Last synced: about 2 months ago
JSON representation
🚀 Performance focused, lightweight scroll animation library 🚀
- Host: GitHub
- URL: https://mciastek.github.io/sal/
- Owner: mciastek
- License: mit
- Created: 2017-09-27T20:37:38.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T04:11:22.000Z (about 2 years ago)
- Last Synced: 2024-11-13T05:38:24.206Z (2 months ago)
- Language: HTML
- Homepage: https://mciastek.github.io/sal/
- Size: 1.65 MB
- Stars: 3,603
- Watchers: 47
- Forks: 179
- Open Issues: 41
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-fe-resources - Sal - Performance focused, lightweight (less than 2.8 kb) scroll animation library, written in vanilla JavaScript. No dependencies! (Table of Contents / JavaScript)
README
# Sal [](https://www.npmjs.com/package/sal.js) [](https://github.com/mciastek/sal/blob/master/LICENSE) [](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).