Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jshjohnson/animate
A tiny JS (5KB) library to trigger animations on elements when they are within the viewport 👓
https://github.com/jshjohnson/animate
animation trigger-animations vanilla-js viewport viewport-animations
Last synced: about 19 hours ago
JSON representation
A tiny JS (5KB) library to trigger animations on elements when they are within the viewport 👓
- Host: GitHub
- URL: https://github.com/jshjohnson/animate
- Owner: jshjohnson
- License: mit
- Created: 2015-10-29T21:14:00.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2022-12-30T18:17:01.000Z (about 2 years ago)
- Last Synced: 2024-10-30T04:50:11.875Z (3 months ago)
- Topics: animation, trigger-animations, vanilla-js, viewport, viewport-animations
- Language: CSS
- Homepage: https://joshuajohnson.co.uk/Animate/
- Size: 1.18 MB
- Stars: 358
- Watchers: 13
- Forks: 38
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Animate.js [](https://github.com/jshjohnson/Animate/actions) [](https://github.com/jshjohnson/Animate/actions) [](https://www.npmjs.com/package/animate.js)
A tiny library (~6kb) written in TypeScript to trigger animations on elements when they come into view 👓.
[Demo](https://joshuajohnson.co.uk/Animate/)
----
### Interested in writing your own JavaScript plugins? Check out [ES6.io](https://ES6.io/friend/JOHNSON) for great tutorials!
----
## Setup
```html
var animate = new Animate({
target: '[data-animate]',
animatedClass: 'js-animated',
offset: [0.5, 0.5],
delay: 0,
remove: true,
scrolled: false,
reverse: false,
onLoad: true,
onScroll: true,
onResize: false,
disableFilter: false,
callbackOnInit: function() {},
callbackOnInView: function(el) {},
callbackOnAnimate: function(el) {},
});
animate.init();
```
## Installation
To install via NPM, run `npm install animate.js`
## Options
#### target
Type: `String` Default: `[data-animate]`
Element(s) reference to target (`querySelectorAll` is called against this value). Once this element is in view, add animations.
#### animatedClass
Type: `String` Default: `js-animated`
Class to be added to element once animation has completed.
#### offset
Type: `Array/Number` Default: `[0.5, 0.5]`
The vertical and horizontal percentages of the element that needs to be in the viewport before the animation triggers. If a single number is passed instead of an array, that number will be used for both the vertical and horizontally offset.
*Examples*
```js
// Trigger animations when 50% of an elements height
// is within the viewport and 100% of its width:
var animate = new Animate({
target: '[data-animate]',
animatedClass: 'visible',
offset: [0.5, 1],
});
// Trigger animations when 100% of an elements height
// is within the viewport and 25% of its width:
var animate = new Animate({
target: '[data-animate]',
animatedClass: 'visible',
offset: [1, 0.25],
});
// Trigger animations when 50% of an elements height
// is within the viewport and 50% of its width:
var animate = new Animate({
target: '[data-animate]',
animatedClass: 'visible',
offset: 0.5,
});
```
#### delay
Type: `Number` Default: `0`
Milisecond delay before animation is added to element in view.
#### remove
Type: `Boolean` Default: `true`
Whether animation classes should removed when the animations complete.
#### reverse
Type: `Boolean` Default: `false`
Once the element has left the top of the viewport (by the same offset), remove the animations from element. When the element comes back into view, it will animate again.
#### scrolled
Type: `Boolean` Default: `false`
Animate any elements that a user has already scrolled past on load. This will only trigger if the `onLoad` option (see below) is `true`.
#### onLoad
Type: `Boolean` Default: `true`
Whether to fire on DOMContentLoaded.
#### onScroll
Type: `Boolean` Default: `true`
Whether to fire on scroll.
#### onResize
Type: `Boolean` Default: `false`
Whether to fire on resize.
### disableFilter
Type: `Function` Default: `null`
Function to determine whether Animate should animate elements.
*Example*
```js
// Function to determine whether we are on a mobile device
var isMobile = function() {
if (window.matchMedia("(max-width: 480px)").matches) {
return true;
} else {
return false;
}
};
// Disable Animate.js if isMobile returns true
var animate = new Animate({
onResize: true,
disableFilter: isMobile,
});
```
#### callbackOnInit
Type: `Function` Default: `function(){}`
Function to run once Animate.js initialises
#### callbackOnInView
Type: `Function` Default: `function(el){}`
Function to run once the element is in the viewport (pass parameter to access the element).
#### callbackOnAnimate
Type: `Function` Default: `function(el){}`
Function to run once animation has completed (pass parameter to access the animated element).
## Element overrides
##### `data-animate`
Default way of targeting an element to animate (no value required). This can be overridden to be a custom attribute or class.
##### `data-animation-classes`
Animations to be added to element when it is in view. To add multiple classes, seperate each class with a space (as you would normally).
### Optional element overrides
##### `data-animation-delay`
Overide the plugin `delay` option per element.
##### `data-animation-offset`
Override the plugin `offset` option per element.
##### `data-animation-remove`
Overide the plugin `removeAnimations` option per element.
##### `data-animation-reverse`
Overide the plugin `reverse` option per element.
#### Examples
```html
```
## Methods
#### init();
Initialises event listeners.
#### kill();
Kills event listeners and resets options.
#### render();
Adds/removes animations without the need for event listeners.
## Browser compatibility
Animate.js is supported in modern browsers from IE9 and above (i.e. browsers that support CSS animations). Due to discrepencies in support for `Element.classList`, I would recommend including the very good [classList polyfill](https://github.com/eligrey/classList.js/) before you include animate.js. I would also suggest using Modernizr to feature detect CSS animations/transitions and apply override styling for browsers that do not support those features.
Using SCSS, this may look like this:
```css
.animate {
opacity: 0;
.no-csstransitions &, .no-cssanimations & {
opacity: 1;
}
}
```
## Development
To setup a local environment: clone this repo, navigate into it's directory in a terminal window and run the following command:
* ```npm install```
### Gulp tasks
* ```npm run dev```
* ```npm run test```
* ```npm run build```
## Contributions
In lieu of a formal style guide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Gulp...bla bla bla
## License
MIT License