UnifiedTransform.js - Combining CSS/SVG Transforms into a single Transform

UnifiedTransform.js is published as unifiedtransform. It parses and composes two-dimensional CSS/SVG transform operations into one affine matrix and can apply that matrix to points.

Use it to flatten nested 2D transforms, combine generated transform fragments, or convert between CSS and matrix layouts. Use DOMMatrix when the target runtime provides it and browser-native integration is desired, or a 3D matrix library for perspective and three-dimensional transforms.

Example / Motivation

<div style="transform: translate(15px, 400px) scale(0.3);">
  <div style="transform: rotate(85deg);">
    <div style="transform: translateY(100px) rotate(33deg);">rawr</div>
  </div>
</div>

Then apply UnifiedTransform.js:

import UnifiedTransform from 'unifiedtransform';

const cm = new UnifiedTransform();

cm.transform('translate(15px, 400px) scale(0.3)');
cm.rotate(85);
cm.transform('translateY(100px) rotate(33deg)');

document.getElementById('newDom').style.transform = cm.toTransformString();

Which simplifies the HTML to:

<div id="newDom">rawr</div>

Recipes

Compose translation and scale

Methods are applied in call order and mutate the same UnifiedTransform instance.

import UnifiedTransform from 'unifiedtransform';

const transform = new UnifiedTransform()
  .translate(10, 20)
  .scale(2);

console.log(transform.eval(1, 1)); // [12, 22]
console.log(transform.toMatrix('CSS')); // [2, 0, 0, 2, 10, 20]
console.log(transform.toTransformString()); // "matrix(2, 0, 0, 2, 10, 20)"

Changing the call order changes the result. eval() returns a new two-element array and does not mutate its arguments.

Parse a CSS transform list

Numeric rotate() arguments are degrees. String rotations accept deg or rad; translations accept pixel strings.

import UnifiedTransform from 'unifiedtransform';

const transform = new UnifiedTransform()
  .transform('translate(10px, 20px) rotate(90deg)');

console.log(transform.eval(1, 0).map((value) => +value.toFixed(12)));
// [10, 21]

The parser supports matrix, translate, translateX, translateY, scale, rotate, skewX, and skewY. Unsupported functions such as 3D or perspective transforms are ignored.

Rotate around a point

The optional second and third arguments to rotate() define the rotation center.

import UnifiedTransform from 'unifiedtransform';

const transform = new UnifiedTransform().rotate(90, 5, 5);
console.log(transform.eval(6, 5).map((value) => +value.toFixed(12)));
// [5, 6]

All transformation methods mutate and return the receiver for chaining. There is no clone method; create a new instance before building an independent transform.

Methods

UnifiedTransform transform(str)

Parses a transform string and applies each transformation one after the other

UnifiedTransform translate(tx, ty)

Specifies a 2D translation by the vector (tx, ty)

UnifiedTransform scale(sx, sy = null)

Specifies a 2D scale operation by the (sx, sy) scaling vector described by the 2 parameters. If the second parameter is omitted, the scaling is applied symmetrically.

UnifiedTransform rotate(angle[, x, y])

Specifies a 2D rotation by the angle specified in the parameter about the origin of the element or optionally the given point (x, y)

UnifiedTransform skewX(degrees)

Specifies a 2D skew transformation along the X axis by the given angle.

UnifiedTransform skewY(degrees)

Specifies a 2D skew transformation along the Y axis by the given angle.

UnifiedTransform applyMatrix(m[, order="CSS" | "2D" | "flat"])

Specifies a 2D transformation in the form of a transformation matrix. With

• order="CSS" (default) a 6 element array [a, b, c, d, x, y] is expected
• order="2D" a 3x3 array is expected
• order="flat" a 9 element array in classic row format is expected

Array eval(x, y)

Evaluates a point using the current transformation matrix and returns the new point

Array toMatrix([order="CSS" | "2D" | "flat"])

Gets the transform matrix of the current homogeneous transformation. With

• order="flat" (default) a flat 9 element array in the classic row format is returned
• order="2D" a 3x3 array is returned
• order="CSS" a 6 element array [a, b, c, d, x, y] is returned

String toTransformString()

Gets a CSS transform string to apply the current matrix

Installation

You can install UnifiedTransform.js via npm:

npm install unifiedtransform

Or with yarn:

yarn add unifiedtransform

Alternatively, download or clone the repository:

git clone https://github.com/rawify/UnifiedTransform.js

Usage

CommonJS

const UnifiedTransform = require('unifiedtransform');
const transform = new UnifiedTransform();

ES modules

import UnifiedTransform, { UnifiedTransform as NamedUnifiedTransform } from 'unifiedtransform';
const transform = new UnifiedTransform();

Standalone browser script

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/unifiedtransform.min.js"></script>
<script>
  const transform = new UnifiedTransform();
</script>

Native browser module

<script type="module">
  import UnifiedTransform from 'https://cdn.jsdelivr.net/npm/[email protected]/dist/unifiedtransform.mjs';
  const transform = new UnifiedTransform();
</script>

The package has no runtime dependencies and supports Node.js 20 or newer. CommonJS consumers can use the direct class export as well as its .default and .UnifiedTransform aliases. These compatibility paths are covered by the test suite and are part of the supported API.

Building the library

The implementation is written in strict TypeScript. The build emits CommonJS, ES modules, a standalone browser bundle, source maps, and format-specific type declarations without modifying source or documentation files.

After cloning the Git repository, run:

npm install
npm run build

Run a test

Testing the source against the shipped test suite is as easy as

npm run test

Copyright and Licensing

Copyright (c) 2026, Robert Eisele Licensed under the MIT license.