API reference

Each of the functions documented below has a complementary relative transform function, which can be used simply by appending R to the function name. For example, to use the relative version of the translate function, call translateR.

Some functions have specialised variants which only apply the given transform to one axis—for example, skew has skewX and skewY. These axis functions will be mentioned together after the primary function description: they all have the same signature and work in the same way, save for applying the transform in question to different axes.

When using a relative axis function, the R always goes on the end, so the relative version of scale applied to the Y axis would be scaleYR.

Some functions have aliases—for example, scale is aliased as scale3d. This is solely to maintain parity at the API level with the various CSS transform specifications.

In the examples that follow, animation durations will often be omitted in order to focus on the transformation at hand. However, the default duration is 0, so the duration argument must be passed if a transformation is not to be executed immediately with no intermediate stages (i.e., without animating).

animate

Firmin.animate(element, description, [duration], [callback])

The animate function is the foundation of Firmin’s API: every other transform function is essentially a wrapper around its functionality. Everything one can do with the other transform functions, one can do with animate, although it is usually less convenient.

The description object describes the animation to be carried out. For example, this animation would move the element 400 pixels to the right and double its height.

var el = document.getElementById("an-element"),
    tf = {
        translateX: 400,
        scaleY:     2
    };

Firmin.animate(el, tf);

Instead of using animate with a transform description, one can use the named transform functions. Each transform function (e.g. translateX, skewY) accepts a transform value as its second argument. This value is also what should be used in the transform object when calling animate. In other words,

Firmin.animate(el, {skewX: "1rad"});

is equivalent to

Firmin.skewX(el, "1rad");

The optional duration argument specifies the duration of the animation in seconds; the default value is 0.

A callback function can also be supplied. It will be executed when the animation is complete. For example, running the following would rotate the element through 135° and then change its contents to the string “Hello, world” when the animation completed after 0.7 seconds. Callbacks can be passed to all animation functions and methods.

Firmin.rotate(el, "135deg", "0.7s", function(elem) {
    elem.innerHTML = "Hello, world";
});

The animate function also allows the animation it creates to be customised further, by providing transition properties in the description object.

Firmin.animate(el, {
    translateX:     200,
    timingFunction: "ease-in-out",
    delay:          -0.5
}, 2);

As well as transformations, other CSS properties can be modified by animations. For example, modifying an element’s opacity is quite common.

Firmin.animate(el, {
    opacity: 0.5,
    padding: "10px"
}, "250ms");

Translation functions

translate

Firmin.translate(element, distances, [duration], [callback])

The distances object can have three properties: the x (horizontal), y (vertical) and z (depth) distances which the element should be translated by. All distances must be numbers—the units are pixels. For example, the following translation would move the element 200 pixels to the right and 100 pixels upwards.

Firmin.translate(el, {
    x: 200,
    y: -100
});

Any of the three axis arguments may be omitted.

translate3d

translate3d is an alias for translate, with the same interface and functionality.

translateX, translateY, translateZ

Firmin.translateX(element, distance, [duration], [callback])

The distance of the translation must be a number, representing the number of pixels the element is to be translated by along the relevant axis. E.g., shifting it 50 pixels downwards would be accomplished by:

Firmin.translateY(el, 50);

Scaling functions

scale

Firmin.scale(element, magnitudes, [duration], [callback])

The magnitudes object can have three properties: the x (horizontal), y (vertical) and z (depth) values which the element is to be scaled by. Changes of scale are pure magnitudes; they have no units. As such, they should be positive numbers. For example, to scale an element to twice its width and two-thirds of its height:

Firmin.scale(el, {
    x: 2,
    y: 2/3
});

scale3d

scale3d is an alias for scale, with the same interface and functionality.

scaleX, scaleY, scaleZ

Firmin.scaleX(element, magnitude, [duration], [callback])

The magnitude by which the element should be scaled by must be a positive number. To scale an element to four times its depth:

Firmin.scaleZ(el, 4);

Rotation functions

rotate

Firmin.rotate(element, angle, [duration], [callback])

The angle by which the element will be rotated can be specified as a string, in which case it will be parsed as an angle, or as a number, in which case it is assumed that the angle is given in degrees.

The rotate function will rotate an element by the given angle in the plane of the web page, i.e. about the Z axis.

rotate3d

Firmin.rotate3d(element, description, [duration], [callback])

The description object should contain four properties: x, y and z values, and an angle value specifying the angle through which the element should be rotated. The x, y and z properties should be given as numbers: taken together, they are interpreted as a vector about which the element is to be rotated. The angle property should be a string or number specifying a CSS angle.

In this example, the element would be rotated about the vector (0.25, 0.5, 0.75) by 1 radian.

Firmin.rotate3d(el, {
    x:     0.25,
    y:     0.5,
    z:     0.75,
    angle: "1rad"
});

If any of the directional properties are not given, they will be assigned the value 0. In the following example, the element would be rotated 60° about the vector (0.5, 0, 0.3).

Firmin.rotate3d(el, {
    x:     0.5,
    z:     0.3,
    angle: 60
});

rotateX, rotateY, rotateZ

Firmin.rotateX(element, angle, [duration], [callback])

These functions rotate the element about the given axis rather than an arbitrary vector, as the rotate3d function does. The angle should be given as a string or a number.

Skew functions

skew

Firmin.skew(element, angles, [duration], [callback])

A skew transformation along the X and Y axes is specified via an angles object with two properties: the x and y angles by which the element will be skewed. These should be given as angles or numbers. Either of these properties may be omitted and will in that case just be set to 0.

Firmin.skew(el, {
    x: "20deg",
    y: "1rad"
});

skewX, skewY

Firmin.skewX(element, angle, [duration], [callback])

The angle by which the element will be skewed should be an angle or a number. Note that HTML elements are two-dimensional, and so there is no skewZ function as it would not make sense to skew an HTML element along the Z axis.

In this example, the element would be skewed by 30° along the Y axis.

Firmin.skewY(el, "30deg");

Matrix functions

matrix

Firmin.matrix(element, vector, [duration], [callback])

The vector supplied expresses a two-dimensional transformation matrix. It should have either 6 or 16 elements, depending on whether one wishes to specify a 2D or a 3D transformation.

2D transformations are represented by 3x3 matrices, but as only 6 values of the matrix are needed to compute the transformation, it can be represented as a 6-element vector.

Firmin.matrix(el, [3, 1, 0, 2, 1, 1]);

3D transformations are represented by 4x4 matrices, and in this case all 16 values must be specified, as below. In both cases all values must be numbers; they are interpreted internally as representing either distances in pixels or angles in degrees.

Firmin.matrix(el, [
    -0.5, 0.6, -0.7, 0,
    -0.7, 0.3, 0.7,  0,
    0.6,  0.7, 0.2,  0,
    0,    0,   0,    1
]);

All other transformations can be represented in terms of a transformation matrix—this is what the library does internally. The matrix function can be useful when generating animations programmatically, but any transformation definable using this function can be described more perspicuously with either the named transform functions or a judicious use of animate.

matrix3d

matrix3d is an alias for matrix, with the same interface and functionality.