transition.js is a JavaScript library that provides a convenient way to create CSS transitions pragmatically.

Download

API

transition.begin(element, properties[, options])

Summary

The begin method applies CSS transition effect on the passed element using the passed properties that define the transition effect.

Parameters

element

The element on which the CSS transition effect will be applied.

properties

The transition properties of a single or multiple CSS transitions. This parameter can take several forms:

Array: ["opacity", "0", "1", "1s", "linear", "0s", onTransitionEndCallback]
Array of transition properties and transition values. The first three values are required and must be specified in the following order: a CSS transition property name, a value to transition "from" and a value to transition "to". The rest of the values (duration, delay, timing function and onTransitionEnd callback) are optional and their order conforms to the CSS transition property specification: the first value that can be parsed as a time is assigned to the transition-duration, and the second value that can be parsed as a time is assigned to transition-delay.
String: "opacity 0 1 1s linear 0s"
String with space separated transition properties and transition values. The order and the requirements of the values in this string must follow the same rules defined for the values specified inside an array. Due to its nature, this form does not allow specifying the onTransitionEnd callback.
Note: some CSS properties (e.g.: transform) can themselves receive a space separated values such as transform: translateX(200px) rotate(180deg);. In this case, you should use the "Array" form.
Object: {property: "opacity", from: "0", to: "1"}
Using this form, you can specify all the properties you can specify using the array form (property name, from value, to value, duration, delay, timingFunction and onTransitionEnd callback). But also the beginFromCurrentValue flag, see examples below for more info.
Array of Arrays, Strings or Objects
Array of Arrays, Strings or Objects, each specifying single transition property. This form allows transitioning multiple transition properties on a single element at once:
["opacity 0 1 1s", ["color", "red", "blue", "500ms"]]
options

Transition options object with the following optional fields:

onTransitionEnd
A callback function that is called when all transition properties have finished their transitions. Receives two parameters, element and finished. The finished parameter will be false if the transition was stopped or one of the transitioned properties was used in a new transition.
onBeforeChangeStyle
A callback function that is called before the new CSS property value is applied to the element. This callback tries to mimic the before-change style event.
onAfterChangeStyle
A callback function that is called after the new CSS property value is applied to the element. This callback tries to mimic the after-change style event.
beginFromCurrentValue
Sets the default beginFromCurrentValue value for properties that do not specify their own beginFromCurrentValue value. See examples below for more info.
duration
Sets the default transition-duration for the transition properties that do not specify their own duration. Default is 400ms.
delay
Sets the default transition-delay for the transition properties that do not specify their own delay. Default is 0s.
timingFunction
Sets the default transition-timing-function for the transition properties that do not specify their own timing-function. Default is ease.

Returns

An object with a promise field holding a Promise that will be resolved when the transition ends. In a similar way to the onFulfilled callback, the promise resolves with an object having two fields: the animated element and the finished flag that indicating if the transition finished animating.

Examples

Single property transition
To perform CSS transition on a single property of an element, specify the element and the array with transition values.
function animate(element) {
    transition.begin(element, ["background-color", "#ffffff", "#ADB5C7", "500ms", "linear"]);
}
animate(element)
You can also specify a string with space separated values instead of an array. The order of the values in string must follow the same rules defined for the values specified in an array.
function animate(element) {
    transition.begin(element, "background-color #ffffff #ADB5C7 500ms linear");
}
animate(element)
You have also more verbose way to specify the transition values as an object.
function animate(element) {
    transition.begin(element, {
        property: "background-color",
        from: "#ffffff",
        to: "#ADB5C7",
        duration: "500ms",
        timingFunction: "linear"
    });
}
animate(element)
Multiple properties transition
To perform CSS transition on multiple properties, specify the element and the array of arrays with transition values.
function animate(element) {
    transition.begin(element, [
        ["transform", "translateX(0)", "translateX(200px)", "1s", "ease-in-out"],
        ["background-color", "#ffffff", "#ADB5C7", "500ms", "linear"]
    ]);
}
animate(element)
As with single property transition, you can specify an array of strings with space separated values.
function animate(element) {
    transition.begin(element, [
        "transform translateX(0) translateX(200px) 1s ease-in-out",
        "background-color #ffffff #ADB5C7 500ms linear"
    ]);
}
animate(element)
Multiple properties transition with default transition values
If some or all properties share the same transition values like duration or timing function, you can pass these values inside the third options argument. Transition values specified for a specific transition property will override shared transition values.
function animate(element) {
    transition.begin(element, [
        ["transform", "translateX(0)", "translateX(200px)"],
        ["background-color", "#ffffff", "#ADB5C7", "2s"]
    ], {
        // Both "transform" and "background-color" transitions will use "linear" timing function
        timingFunction: "linear",
        // Only "transform" will use "500ms" duration, the "background-color" transition defines
        // its own duration of "2s"
        duration: "500ms"
    });
}
animate(element)
Multiple properties from multiple begin calls
Sometimes it may be easier to transition multiple properties of the same element from different begin calls. Yet, keeping the requirement that all properties begin their transitions simultaneously. Transition.js ensures that all transitions executed in the same JavaScript execution context stack will be started together in a separate execution context stack.
function animate(element) {
    transition.begin(element, ["transform", "translateX(0) rotate(0)", "translateX(200px) rotate(180deg)", "1s", "ease-in-out"]);
    transition.begin(element, ["background-color", "#ffffff", "#ADB5C7", "1s", "ease-in-out"]);
}
animate(element)
Transition with onTransitionEnd callback
The onTransitionEnd callback is fired when all properties finish their transitions. This callback receives two parameters: an element on which the transition was performed, and a boolean flag finished specifying if the transition was finished by reaching its target value (true), or halted (false), for example when another transition with the same transition properties has began.
function animate(element, trFrom, trTo, clrFrom, clrTo, stop) {
    transition.begin(element, [
        ["transform", "translateX(" + trFrom + ")", "translateX(" + trTo + ")"],
        ["background-color", clrFrom, clrTo]
    ], {
        duration: "1s",
        timingFunction: "ease-in-out",
        onTransitionEnd: function(element, finished) {
            if (!finished || stop) return;
            // Animate backwards by switching values
            animate(element, trTo, trFrom, clrTo, clrFrom, true);
        }
    });
}
animate(element, '0', '200px', '#ffffff', '#ADB5C7', false)
Properties with onTransitionEnd callback
Every property can have its own onTransitionEnd callback which is executed as soon as the property finish its transition. Similarly to transition's onTransitionEnd callback, this callback sldo receives two parameters, the element and the finished flag.
function animate(element) {
    transition.begin(element, [
        ["transform", "rotate(0)", "rotate(360deg)", "2s"],
        ["background-color", "#ffffff", "#ADB5C7", "1s", function(element, finished) {
            if (!finished) return;
            transition.begin(element, ["background-color", "#ADB5C7", "#ffffff", "1s"]);
        }]
    ], {
        timingFunction: "linear"
    });
}
animate(element)
Transition with onBeforeChangeStyle callback
The onBeforeChangeStyle callback is called after the "from" values of all transition properties were set on the element and before setting the "to" and transition values. It receives single parameter, the element, on which the transition is performed. This callback tries to mimic the behaviour of the before-change style event. This callback is useful when additional element manipulation is required before beginning the transition, for example setting element's display value to block when performing fade-in transition.
function animate(element) {
    transition.begin(element, ["opacity 0 1 1s", "transform translateX(0) translateX(200px) 1s ease-in-out"], {
        onBeforeChangeStyle: function(element) {
            element.style.display = "block";
        },
        onTransitionEnd: function(element, finished) {
            if (!finished) return;
            element.style.display = "none";
        }
    });
}
animate(element)
Transitioning property from its current value
Sometimes, when beginning new transition with a property that is already being transitioned, it is desired to transition that property from its current value. For example, assume you have two transitions, "fadeIn" and "fadeOut" transitioning values of the "opacity" from 0 to 1 and from 1 to 0 respectively. To ensure these transitions transition opacity from its current value, set the beginFromCurrentValue option to true.
function animate(element) {
    // Go ahead and click on the "animate" button while the previous transition is running.
    // The transition will begin from the current value of transform and not from 0 or 200px.
    if (element._side == "right") {
        element._side = "left";
        transition.begin(element, "transform translateX(200px) translateX(0) 1s", {
            beginFromCurrentValue: true
        });
    } else {
        element._side = "right";
        transition.begin(element, "transform translateX(0) translateX(200px) 1s", {
            beginFromCurrentValue: true
        });
    }
}
animate(element)
Adding new transition to an element with already running transition
You can safely add new transitions to an element with already running transitions.
function animate(element) {
    element.style.backgroundColor = "#ffffff";
    transition.begin(element, "transform translateX(0) translateX(200px) 2s ease-in-out");
    window.clearTimeout(element._timeout);
    element._timeout = window.setTimeout(function() {
        transition.begin(element, "background-color #ffffff #ADB5C7 1s linear");
    }, 1000);
}
animate(element)
Of course, same can be done using CSS transition delay property.
function animate(element) {
    transition.begin(element, [
        "transform translateX(0) translateX(200px) 2s ease-in-out",
        "background-color #ffffff #ADB5C7 1s linear 1s"
    ]);
}
animate(element)