Animate CSS

Animates any animatable CSS property on an HTML DOM element via CSS transitions
Creates an animation effect on CSS property via CSS transitions and returns an Animation Object. Any existing animations under the same property on the element that are currently animating but not completed will be stopped and interrupted prior to starting.

animate(HTMLElement: element, Object: options[property, easing, duration, callback]): Object

Syntax used to animate a single CSS property without explicitly providing a start value. The starting value will be determined by the currently rendered CSS style on the element. In the case that the start value for the property is not explicit set, animate will still be able to calculate the rendered value. Works on all values including those set to auto, initial, unset.

animate(node,
{
    height: '300px',
    easing: 'easeInExpo',
    duration: 1000,
    callback: () => console.log('complete')
});

animate(HTMLElement: element, Object: options[property, easing, duration, callback]): Object

Syntax used to animate a single CSS property while explicitly providing a start value. The starting value will be determined by the currently rendered CSS style on the element. In the case that the start value for the property is not explicit set, animate will still be able to calculate the rendered value. Works on all values including those set to auto, initial, unset.

animate(node,
{
    property: 'height',
    from: '10px',
    to: '300px',
    easing: 'easeInExpo',
    duration: 1000,
    callback: () => console.log('complete')
});

animate(HTMLElement: element, Object: options[...property: [to, from, easing, duration, callback] ]): Object

Syntax used to animate multiple CSS properties with independent animation options for each property.

animate(node,
{
    height: { from: '0px', to: '100px', duration: 350, easing: 'easeInOutElastic' },

    opacity: { to: '0', duration: 500, easing: 'linear' }
});

Animation Properties and Values
Animated properties can be provided both in camelCase or hyphen-case (e.g fontSize or font-size).

animate_css(node, { property: 'background-color', from: '#000' to: '#fff' } );

Animated property values should always be provided as a string value e.g 200px.

In addition to explicit values, properties that support 'auto', 'initial', and 'unset' can also be animated. For example to animate the height of element from 0 to it's native height you can supply options as {from: '0px', to: 'auto'}.

animate_css(node, { property: 'height', from: '0px' to: 'auto' } );

Start Values
Start values do not need to be provided explicitly. animate_css will compute any existing CSS property when not provided. It is however more performant to provide a start value so animate_css does not need to calculate the pre-animation rendered style on the element.

animate_css(node, { property: 'height', to: '300px' } );

Duration
Animation duration is provided as an integer in milliseconds and default to 500 milliseconds when not provided.

animate_css(node, { height: '300px', duration: 1000 } );

Callback
When a callback is provided this function will be called when the animation completes with the target Element as the first parameter. When multiple CSS properties are animated under a single animation, the callback will only be called once, when the longest running animation completes.

animate_css(node, { height: '300px', callback: (node) => console.log('completed') } );

In addition to the default callback, start, complete, fail callbacks can be provided. An animation fails when it is either interrupted by another animation or is stopped explicitly.

animate_css(node, { 
    height: '300px', 
    start: (node) => console.log('start'),
    complete: (node) => console.log('complete'),
    fail: (node) => console.log('failed'), 
});

Easing
Easings must be provided in camelCase: Below is a full list of supported easing. For details on easing patterns take a look at easings.net.

Transitions
In rare cases where the CSS property being animated has a CSS transition value applied, this will be overridden while the animation runs. In the edge-case where a transition is applied as an inline style on the element, this will be removed while the animation runs. Once the animation completes, any inline transition properties that were applied will be restored.

Note animate_css will only override the transition value of the property being animated, not all transitions - which ensures it doesn't have any adverse effects.

Return Values

animate_css will always return and Animation Object. Which have three available methods: start, stop, and destroy.

Calling Animation.stop will immediately stop an animation and restore any styling to it's original state. The animation can then be started again using start.

let animation = animate(element, {height: '300px'});

animation.stop();

Calling Animation.destroy will immediately stop an animation and destroy it so it can't be started again.

let animation = animate(element, {height: '300px'});

animation.destroy();

Sandbox
Below is interactive demo to showcase animating various values, click the button to run the animation:

animate(find('.js-animate-css-example'),
{
    width: 
    {
        to : '500px',
        duration: 1000,
    },
    height: 
    {
        to : '200px',
        duration: 1000,
    },
    backgroundColor: 
    {
        to : '#b324ea',
        duration: 2000,
    },
});