Introduction

Matrix transformations made easy.

Introduction

Imagine a HTML element that may have a CSS transform applied. If we want to add 45° of Z-rotation, we have no way to handle this safely in CSS—we’d just risk overwriting an existing transform. So we decide to use JavaScript, and check the current transform...

getComputedStyle(element) returns the computed styles, and inspecting the transform property shows:

'matrix3d(0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)'

It’s here we discover that browsers actually use transformation matrices under the hood to describe rotation, translation, scale and shear. This means if we wish to manage CSS transforms with JavaScript (without overwriting existing transformations), we’re stuck working with matrices.

Rematrix is an easy way to create and combine matrix transformations that work seamlessly with CSS.

Installation

Browser

A simple and fast way to get started is to include this script on your page:

<script src="https://unpkg.com/rematrix"></script>

If you use this method in production, be sure to specify a fixed version number, and use the minified distribution; e.g: https://unpkg.com/rematrix@0.4.1/dist/rematrix.min.js. This improves performance, but also prevents library changes from impacting your project.

This will create the global variable Rematrix.

Module

npm install rematrix

CommonJS

const Rematrix = require('rematrix');

ES2015

import * as Rematrix from 'rematrix';

Guide

Creating Transforms

Most API methods look a lot like CSS, so for example, in CSS if we would write transform: rotateZ(45deg), we can create the same transformation in JavaScript using Rematrix like this:

Rematrix.rotateZ(45)

This returns a 45° rotation along the Z-axis, represented as an array of 16 values:

[0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]

These 16 values represent our transformation matrix in column-major order.

Combining Transforms (Using Multiplication)

Where Rematrix really outshines CSS, is the ability to combine transforms — using matrix multiplication. We’ll recreate the same 45° rotation along the Z-axis, but using separate matrices this time:

var r1 = Rematrix.rotateZ(20);
var r2 = Rematrix.rotateZ(25);

var product = Rematrix.multiply(r1, r2);

Here product describes the same array of 16 values (seen above):

[0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]

Better Multiplication (Using Reduce)

There’s a good chance we’ll need to multiply quite a few matrices together, so its helpful to store them in an array in order to use Array.prototype.reduce to multiply them all in one line:

var r1 = Rematrix.rotateZ(20);
var r2 = Rematrix.rotateZ(65);
var r3 = Rematrix.rotateZ(-40);

var product = [r1, r2, r3].reduce(Rematrix.multiply);

Order is very important. For example, rotating 45° along the Z-axis, followed by translating 500 pixels along the Y-axis... is not the same as translating 500 pixels along the Y-axis, followed by rotating 45° along on the Z-axis.

Preserving Transforms

Before applying any of our transforms, we should capture the existing transform of our element using Rematrix.fromString(), e.g:

var element = document.querySelector('#example');
var style = getComputedStyle(element).transform;

var transform = Rematrix.fromString(style);

var r1 = Rematrix.rotateZ(20);
var r2 = Rematrix.rotateZ(65);
var r3 = Rematrix.rotateZ(-40);

var product = [transform, r1, r2, r3].reduce(Rematrix.multiply);

By passing the computed transform styles to Rematrix.fromString(), we create a matrix of the existing transform. We can now factor this into our multiplication.

The existing transformation has been deliberately placed at the start of the array to ensure the computed transform is the foundation for the succeeding transformations.

Applying Transforms

We can turn our matrix into valid CSS using Rematrix.toString(), which we can apply to our element’s style, e.g:

element.style.transform = Rematrix.toString(product);

And that concludes this introduction to Rematrix. Please explore the finished Live Demo on JSFiddle.

API Reference

Rematrix

Rematrix.fromString(source) ⇒ `array`

Attempts to return a 4x4 matrix describing the CSS transform matrix passed in, but will return the identity matrix as a fallback.