jshjohnson / animate

A tiny JS (5KB) library to trigger animations on elements when they are within the viewport 👓

Animate.js

A tiny library (~6kb) written in TypeScript to trigger animations on elements when they come into view 👓.

Demo

---

Interested in writing your own JavaScript plugins? Check out ES6.io for great tutorials!

---

Setup

<script src="/assets/js/dist/animate.js"></script>
<script>
    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();
</script>

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

// 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

// 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

<div data-animate data-animation-classes="animated fadeIn"></div>
<div data-animate data-animation-classes="animated tada" data-animation-delay="1000"></div>
<div data-animate data-animation-classes="animated bounce" data-animation-offset="0.2, 0.5"></div>
<div data-animate data-animation-classes="animated bounce" data-animation-remove="true"></div>

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 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:

.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

animate's Issues

Could `offset` logic be reversed?

Hey,
I was wondering. Could the offset logic also be reversed?
Now the logic is the number of the input is the percentage of which the element is visible in the viewport.
I would like to see a way to input a number of the percentage of which the element is inside the viewport. So, the other way around. I you would enter 0.1 it checks if the element, not matter the size of the element, had entered 10% of the viewport.

The reason is that, now it works nicely on desktop. But it becomes a mess sometimes on mobile. For example, I've got a block with 2 rows and 4 columns on desktop. But on mobile they are 8 rows of 1 column. In other words, a long-long block. Now you have to scroll, say, 50% of the element to be visible. Leaving the visitor puzzled why for four scrolls nothing shows.

I know I can disable the effect on mobile or even make a conditional second option with an offset of 0.05. But I think a trigger of the view percentage within the viewport would solve a lot for me.

LICENSE file not included in repository root

Optional parameter to test horizontal position of element on screen (as well as vertical).

For example:

    var animate = new Animate({
        offset: [0.5, 0.25],
    });

This would test to see whether at least 50% of the elements height was within the viewport as well as 25% of the elements width. Useful for horizontal scrolling pages.

Animate Timing.

Is there a way to set the animate time?

Add option to use the parent as the offset rather than the child

So when a container is in view for example, animations will trigger on each child with the correct target class/attribute.

Cannot read property 'document' of undefined

Hi Josh,

Thanks for the require.js UMD wrapper fix. We're not out of the woods yet though. I've updated the test case:
Archive.zip

Cheers, Cam

Ability to provide a condition to disable the plugin

For example:

const animate = new Animate('[data-animate'],{
    disableFilter: () => {
        if(isMobile) {
            return false;
        } else {
            return true;
        }
    }
});

Provide classList fallbacks for IE9

Add element `reverse` override

Override the plugin default reset value per element

Ability to specify an element as a container rather than the document.

If you have an element that scrolls with children that need to animate, it would be good if an element could be passed as the container instead of the document.

callbackOnInview - Event listener when Item is in view not just animated

I would like to run a function when element is in view port but the callbackOnAnimate only works if an animation has taken place. This would prevent me having to have further scroll events.

Animation is not working due to missing data-attribute

this._getElemOffset(el) returns undefined when data-animation-offset attribute is not added to the element

Reverse argument doesnt work

I'm having problems with replaying the animation on element re-entry. Tried both the data-attribute way and the js-param way. Any leads on what I'm doing wrong?

Error: "Cannot read property '_debounce' of undefined" on line 32 of animate.js when using require.js

animate.js would appear to be AMD compliant based on the code at the start of the file, however it doesn't seem to play nice with require.js

i've tried adding a shim to export "Animate" but that doesn't work

any clues?

Not replay animation

Animation not replaying if element have position absolute
Video

DOMContentLoaded and asset loaders

Hi,

thank you for this nice "plugin" - finally I found the one that works without jQuery (and works just as good).

I have my own asset loader and it dynamically loads JS and CSS. The problem is that DOMContentLoaded fires before Animate steps in so the setting "onLoad" is not working. Items are loading on scroll but items which are in viewport by default are not.

Is there a way to fix this? I modified animate.js to render() on window.load instead document.DOMContentLoaded so it is working fine now. Perhaps adding a new setting "onWindowLoad"?