Skip to content
thednp edited this page Jan 17, 2026 · 13 revisions

Note: The initialization doesn't support CSS syntax strings with transform functions like rotate() or translate() only matrix() and matrix3d(), or 6/16 elements arrays.

Basics

Version 2.0+:

// ES6+
import CSSMatrix from "@thednp/dommatrix";

// init
const myMatrix = new CSSMatrix("matrix(1,0.25,-0.25,1,0,0)");

OR

// Node.js
const CSSMatrix = require("@thednp/dommatrix");

// init
const myMatrix = new CSSMatrix("matrix(1,0.25,-0.25,1,0,0)");

Older versions:

// ES6+
import CSSMatrix from "dommatrix";

// init
const myMatrix = new CSSMatrix("matrix(1,0.25,-0.25,1,0,0)");

OR

// Node.js
const CSSMatrix = require("dommatrix");

// init
const myMatrix = new CSSMatrix("matrix(1,0.25,-0.25,1,0,0)");

Check the CSSMatrixInput to learn more.

Advanced API Examples

Provide Values on Initialization

// the above are equivalent with providing the values are arguments
// or by providing an Array, Float32Array, Float64Array
const myMatrix = new CSSMatrix([1, 0.25, -0.25, 1, 0, 0]);

Use Static Methods to Initialize

// fromMatrix will create a clone of the above matrix
const myMatrix = CSSMatrix.fromMatrix(myTranlateMatrix);

// create a new CSSMatrix from an Array, Float32Array, Float64Array
const myMatrix = CSSMatrix.fromArray([1, 0.25, -0.25, 1, 0, 0]);

// create a new CSSMatrix from a valid CSS transform syntax
const myMatrix = CSSMatrix.fromString("perspective(400px) rotateX(0.5rad)");

Provide valid CSS syntax

// create a new CSSMatrix from any transform string
const myMatrix = new CSSMatrix("matrix(1,0.25,-0.25,1,0,0)");

// regular transforms also supported
const myMatrix = new CSSMatrix("translate(150px, 150px) rotate(0.5rad)");

Using Main Methods

// call methods to apply transformations via IMMUTABLE methods
const myMatrix = new CSSMatrix().translate(15);

// equivalent to
const myMatrix = new CSSMatrix().translate(15, 0);

// equivalent to
const myMatrix = new CSSMatrix().translate(15, 0, 0);

// rotations work as expected
const myMatrix = new CSSMatrix().rotate(15);

// equivalent to
let myMatrix = new CSSMatrix().rotate(0, 0, 15);

// also equivalent to
const myMatrix = new CSSMatrix().rotateAxisAngle(0, 0, 1, 15);

Using Mutable Methods

// call methods to apply transformations via MUTABLE methods
const myMatrix = new CSSMatrix().translateSelf(15);

// equivalent to
const myMatrix = new CSSMatrix().translateSelf(15, 0);

// equivalent to
const myMatrix = new CSSMatrix().translateSelf(15, 0, 0);

// rotations work as expected
const myMatrix = new CSSMatrix().rotateSelf(15);

// equivalent to
let myMatrix = new CSSMatrix().rotateSelf(0, 0, 15);

// also equivalent to
const myMatrix = new CSSMatrix().rotateAxisAngleSelf(0, 0, 1, 15);

Manipulate The Matrix values

// replace existing matrix with values from array
// as if your're re-initializing the matrix
myMatrix.setMatrixValue(1, 0.25, -0.25, 1, 0, 0);

// apply additional transformations to an existing matrix
// by calling instance methods
myMatrix.translateSelf(15).skewXSelf(45);
// OR this is equivalent to DOMMatrix.translateSelf()
// myMatrix = myMatrix.translate(15).skewX(45);

// apply additional transformations to an existing matrix
// by calling a static method to create a new matrix;
// the result of the multiply instance method and
// the result of the Rotate static method combined create
// a third CSSMatrix instance that replaces the original
// matrix entirely
rotationMatrix = CSSMatrix.Rotate(0, 45, 0, 0);
myMatrix.multiplySelf(rotationMatrix);
// this is equivalent to the following
// myMatrix = myMatrix.multiply(rotationMatrix);

Exporting The Matrix

// export to the CSS transform string syntax
let myMatrix = new CSSMatrix().translate(15).toString();

// export to Array
// if the matrix is 2D, the [a, b, c, d, e, f] matrix is exported
let myMatrix = new CSSMatrix().rotate(45).toFloat64Array();

// export to JSON
// if the matrix is 2D, the 2D matrix() function is used
let myMatrix = new CSSMatrix().rotate(45).toJSON();

Adding Perspective To Matrix

// perspective
let perspective = 400;

// init
let myMatrix = new CSSMatrix();

// set perspective
myMatrix.m34 = -1 / perspective;

// now your matrix is always 3D
// we can apply any 3D transformation
myMatrix.rotateSelf(45, 0, 0);

// this matrix is now equivalent with this
// CSS transformation syntax
// perspective(400px) rotateX(45deg)

Clone this wiki locally