README

Velvet

A JavaScript library for DOM animations as smooth as Velvet, which was inspired by Velocity and jQuery Transit.

TL;DR

See demo page.

Features

Animations with JavaScript
It's a sort of manipulator to easily manipulate an element's transform property with JavaScript. You can freely play, pause and reverse the animation.
Web Animations API
It preferentially uses Web Animations API, specifically element.animate() if supported.

Policy

Speedster
It pursues speed than Swiss Army knife.
Minimalist
It keeps it as simple and small as possible (3.3kb (minified and gzipped) for now).

Installation

npm:

$ npm install velvetjs

Bower(Deprecated):

$ bower install velvetjs

Usage

CommonJS:

var velvet = require('velvetjs');
var div = velvet(document.getElementById('div'));
div.weave({ translateX: 100 }, { durarion: 400 });

AMD:

require(['path/to/velvet'], function (velvet) {
    var div = velvet(document.getElementById('div'));
    div.weave({ translateX: 100 }, { durarion: 400 });
});

directly:

<script src="/path/to/velvet.min.js"></script>
<script>
    var div = velvet(document.getElementById('div'));
    div.weave({ translateX: 100 }, { durarion: 400 });
</script>

API

velvet([element])

element: One or more target elements. (optional)

The velvet function returns a Velvet object or a Textile object. If call this with a parameter, it returns a Velvet object. If omit the parameter, it returns a Textile object.

var v = velvet(document.getElementById(('div'));    // Returns a Velvet object
var t = velvet();   // Returns a Textile object

Velvet object

v.weave(styles, options)

styles: CSS Styles (transforms and opacity only)
options: Animation options

The weave method creates an animation. The details of arguments are as follows:

var w = v.weave({
    translateX: 100,    // (px)
    translateY: 200,    // (px)
    translateZ: 300,    // (px) Not supported in IE9
    scale: 1.5,     // Equivalent to { scaleX: 1.5, scaleY: 1.5 }
    scaleX: 2,
    scaleY: 2,
    scaleZ: 2,      // Not supported in IE9
    rotate: 30,     // (deg) Equivalent to { rotateZ: 30 }
    rotateX: 45,    // (deg) Not supported in IE9
    rotateY: 60,    // (deg) Not supported in IE9
    rotateZ: 30,    // (deg) Not supported in IE9
    skewX: 45,      // (deg)
    skewY: 45,      // (deg)
    perspective: 400,   // (px)
    opacity: 0.5
}, {
    delay: 1000,    // (ms)
    durarion: 400,  // (ms)
    easing: 'ease', // Any of 'linear', 'ease', 'ease-in', 'ease-out' and 'ease-in-out'
    oncancel: function () {
        // This is called when the animation is canceled.
    },
    onfinish: function () {
        // This is called when the animation is finished.
    }
});

NOTE: Don't append unit for these parameters. 100px -> 100

This method returns a Weaver object and the animation will automatically start.

v.style(styles)

styles: CSS Styles

The style method set styles to the element. Since the above weave method ignores the preset transform and opacity property, you need to set the styles if want to make started the animation from status different from default (position, size, etc.).

// fade-in
v.style({
    translateX: 100,
    opacity: 0
}).weave({
    opacity: 1  // The opacity will transition from 0 to 1
}, {
    duration: 400
});

You may also set other properties with this method.

v.style({
    position: 'absolute',
    left: '10px',   // In this case you need to append unit. 10 -> 10px
    top: '20px'
});

NOTE: Since this method will not take care of Vendor Prefix, for instance, you will need to set them like this:

v.style({
    '-webkit-transform-origin': 'left top'
    '-moz-transform-origin': 'left top'
    '-ms-transform-origin': 'left top'
    'transform-origin': 'left top'
});

Textile object

t.weave(from, to, options, cb)

from: An array of start values
to: An array of end values
options: Animation options
cb: A callback function called per frame

The weave method creates an animation other than transform and opacity. This is an example of scrolling a window:

var w = t.weave([0], [200], {
    delay: 1000,    // (ms)
    duration: 400,  // (ms)
    easing: 'ease', // Any of 'linear', 'ease', 'ease-in', 'ease-out' and 'ease-in-out'
    oncancel: function () {
        // This is called when the animation is canceled.
    },
    onfinish: function () {
        // This is called when the animation is finished.
    }
}, function (values) {
    // The scroll position will transition from 0px to 200px.
    window.scrollTo(0, values[0]);
});

It returns a Weaver object in the same way as v.weave method.

Weaver object

w.pause()

The pause method pauses the animation.

w.play()

The play method resumes the paused animation, or replays the stopped animation.

w.finish()

The finish method goes to the end position of the animation, and stops.

w.cancel()

The cancel method goes back to the start position of the animation, and stops.

w.reverse()

The reverse method reverses the current play direction, and starts to play the animation.

v.weave({
    translateX: 100
}, {
    durarion: 400,
    onfinish: function () {
        this.reverse(); // The animation will be endlessly repeated.
    }
});

w.direction()

The direction method returns current play direction. (1: forward direction, -1: backward direction)

Tips

Position Property

For better performance, set absolute or fixed to the element's position property.

#element {
    position: "absolute";
}

Combo Animations with Promise

In order to create Combo Animations use Promise like this:

var div = velvet(document.getElementById(('div'));

Promise.resolve().then(function () {
    return new Promise(resolve) {
        div.weave({
            translateX: 100     // The translateX will transition from 0 to 100.
        }, {
            duration: 400,
            onfinish: resolve
        });
    };
}).then(function () {
    return new Promise(resolve) {
        div.weave({
            translateY: 100     // The translateY will transition from 0 to 100.
        }, {                    // The X will remain at the same position (100px).
            duration: 400,
            onfinish: resolve
        });
    };
}).then(function () {
    return new Promise(resolve) {
        div.weave({
            translateX: 0,
            translateY: 0       // These will transition from 100 to 0.
        }, {
            duration: 400,
            onfinish: resolve
        });
    };
});

TODO

Proper test
~~Multiple elements control~~
Customizing cubic bezier
Vendor Prefix support for style method
Returning a Promise

Supported browser

Chrome, Firefox, Safari, Opera, Android Browser 4.0+, iOS Safari, Edge and IE9+

Lisence

MIT

Usage no npm install needed!