JavaScript API

Standard Methods

Main instance methods described in the MDN specifications.

translate(x, y, z)

The translate method returns a new matrix which is this matrix post multiplied by a translation matrix containing the passed values. If the z parameter is undefined, a 0 value is used in its place. This matrix is not modified.

Parameters:

• x the X axis component of the translation value.
• y the Y axis component of the translation value.
• z the Z axis component of the translation value.

rotate(rx, ry, rz)

The rotate method returns a new matrix which is this matrix post multiplied by each of 3 rotation matrices about the major axes, first X, then Y, then Z. If the y and z components are undefined, the x value is used to rotate the object about the z axis, as though the vector (0,0,x) were passed. All rotation values are expected to be in degrees. This matrix is not modified.

Parameters:

• rx the X axis component of the rotation value.
• ry the Y axis component of the rotation value.
• rz the Z axis component of the rotation value.

rotateAxisAngle(x, y, z, angle)

This method returns a new matrix which is this matrix post multiplied by a rotation matrix with the given axis and angle. The right-hand rule is used to determine the direction of rotation. All rotation values are in degrees. This matrix is not modified.

Parameters:

• x The X component of the axis vector.
• y The Y component of the axis vector.
• z The Z component of the axis vector.
• angle The angle of rotation about the axis vector, in degrees.

scale(x, y, z)

The scale method returns a new matrix which is this matrix post multiplied by a scale matrix containing the passed values. If the z component is undefined, a 1 value is used in its place. If the y component is undefined, the x component value is used in its place. This matrix is not modified.

Parameters:

• x the X axis component of the scale value.
• y the Y axis component of the scale value.
• z the Z axis component of the scale value.

skewX(angle)

Specifies a skew transformation along the x-axis by the given angle. This matrix is not modified.

The angle parameter sets the amount in degrees to skew.

skewY(angle)

Specifies a skew transformation along the y-axis by the given angle. This matrix is not modified.

The angle parameter sets the amount in degrees to skew.

skew(x, y)

Specifies a skew transformation along both the x-axis and y-axis. This matrix is not modified.

Parameters:

• x the X axis component of the shear value.
• y the Y axis component of the shear value.

toString()

Creates and returns a string representation of the matrix in CSS matrix syntax, using the appropriate CSS matrix notation. The 16 items in the array 3D matrix array are transposed in row-major order.

Depending on the value of is2D, the method will return the CSS matrix syntax in one of the two formats:

• matrix3d(m11,m12,m13,m14,m21,m22,m23,m24,m31,m32,m33,m34,m41,m42,m43,m44)
• matrix(a, b, c, d, e, f)

Additional Methods

multiply(m2)

The multiply method returns a new CSSMatrix which is the result of this matrix multiplied by the passed matrix, with the passed matrix to the right. This matrix as well as the one passed are not modified.

The m2 parameter is expecting a CSSMatrix or DOMMatrix instance.

setMatrixValue(any)

This method replaces the existing matrix with one computed in the browser. EG: matrix(1,0.25,-0.25,1,0,0).

The method also accepts 6/16 elements Float64Array / Float32Array / Array values, the result of CSSMatrix => toFloat64Array() / DOMMatrix => toFloat64Array() / toFloat32Array().

For simplicity reasons, this method expects only valid matrix() / matrix3d() string values, which means other transform functions like translate(), rotate() are not supported.

Parameter:

• The source parameter can be the String representing the CSS syntax of the matrix, which is also the result of getComputedStyle().
• The source can also be an Array resulted from toFloat64Array() method calls.
• To make things even more crazy, the parameter also accepts other CSSMatrix or DOMMatrix instances.

transformPoint(point)

Transforms the specified point using the matrix, returning a new DOMPoint like Object containing the transformed point. Neither the matrix nor the original point are altered.

The method is equivalent with transformPoint() method of the DOMMatrix constructor.

The point parameter expects a DOMPoint or an Object with x, y, z and w components.

toFloat32Array(is2D)

Returns a Float32Array containing elements which comprise the matrix. The method can return either the 16 elements or the 6 elements depending on the value of the is2D parameter.

toFloat64Array(is2D)

Returns a Float64Array containing elements which comprise the matrix. The method can return either the 16 elements or the 6 elements depending on the value of the is2D parameter.

toJSON()

Returns a JSON representation of the CSSMatrix object, a standard Object that includes {a,b,c,d,e,f} and {m11,m12,m13,..m44} properties, including is2D & isIdentity properties.

The result can be used by both CSSMatrix and DOMMatrix via the static method called fromMatrix().

Getters

isIdentity

A Boolean whose value is true if the matrix is the identity matrix. The identity matrix is one in which every value is 0 except those on the main diagonal from top-left to bottom-right corner (in other words, where the offsets in each direction are equal).

is2D

A Boolean flag whose value is true if the matrix was initialized as a 2D matrix and false if the matrix is 3D.

Static Methods

The methods attached to the CSSMatrix Object but not included in the constructor prototype. Some methods aim to be equivalents while others provide utility.

fromMatrix(m2)

Creates a new mutable CSSMatrix instance given an existing matrix instance or a DOMMatrix instance which provides the values for its properties.

The method also accepts JSON files resulted from both CSSMatrix.toJSON() and DOMMatrix.toJSON() instance calls, just like the DOMMatrix does.

The m2 parameter is the matrix instance or JSON object passed into the method and neither this matrix or the one passed are modified.

fromArray(array)

Creates a new mutable CSSMatrix instance from an array of values. If the array has 6 values, the result is a 2D matrix; if the array has 16 values, the result is a 3D matrix. Otherwise, a console.error is thrown.

The array parameter is the source to feed the values for the new matrix.

Both Float64Array and Float32Array are acceptable since this static method uses Array.from.

toArray(m, is2D)

The static method used by toFloat64Array and toFloat32Array instance methods, and can return an Array of 6 elements if the given parameter is2D is true.

The result can be immediately fed as parameter for the initialization of a new matrix.

Parameters:

• The m parameter can be a DOMMatrix / CSSMatrix instance, JSON objects resulted from both CSSMatrix.toJSON() and DOMMatrix.toJSON() instance calls, just like the DOMMatrix does.
• The is2D parameter decides if the returned array should have 16 or 6 values.

fromString(string)

Creates a new mutable CSSMatrix instance from a valid CSS transform string syntax or what's called a TransformList.

The string parameter is the source string to be parsed and feed the matrix.

Some notes on the fromString static method:

• will correctly validate the amount of values each transform function is supposed to have
• will convert radian angles to degrees
• will parseFloat all values
• will not validate the unit each function type is supposed to have, for instance rotate(15px) will be accepted as rotate(15deg), or perspective(150%) will be accepted as perspective(150px), both cases are invalidated by the DOMMatrix constructor.

isCompatibleObject(object)

Checks if an object is compatible with CSSMatrix, usually another CSSMatrix / DOMMatrix instance or the result of these instances toJSON() method call.

isCompatibleArray(array)

Checks if an array is compatible with CSSMatrix, usually an array of 6/16 numbers, or the result of another CSSMatrix / DOMMatrix instance call for one of the toFloat32Array() / toFloat64Array() methods.

/** Checks if an array is compatible with CSSMatrix */ const isCompatibleArray = (array?: unknown): array is Matrix | Matrix3d | Float32Array | Float64Array => { return ( (array instanceof Float64Array || array instanceof Float32Array || (Array.isArray(array) && array.every(x => typeof x === 'number'))) && [6, 16].some(x => array.length === x) ); };

/** Checks if an object is compatible with CSSMatrix */ const isCompatibleObject = (object?: unknown): object is CSSMatrix | DOMMatrix | JSONMatrix => {