\n\n \n\n \n\n# Introduction\n\nImagine 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...\n\n`getComputedStyle(element)` returns the computed styles, and inspecting the `transform` property shows:\n\n```js\n'matrix3d(0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)'\n```\n\nIt’s here we discover that browsers actually use [transformation matrices](https://en.wikipedia.org/wiki/Transformation_matrix) 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.\n\n**Rematrix** is an easy way to create and combine matrix transformations that work seamlessly with CSS.\n\n \n\n# Installation\n\n## Browser\n\nA simple and fast way to get started is to include this script on your page:\n\n```html\n\n```\n\n> 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.7.2/dist/rematrix.min.js`. This improves performance, but also prevents library changes from impacting your project.\n\nThis will create the global variable `Rematrix`.\n\n## Module\n\n```bash\nnpm install rematrix\n```\n\n#### CommonJS\n\n```js\nconst Rematrix = require('rematrix')\n```\n\n#### ES2015\n\n```js\nimport * as Rematrix from 'rematrix'\n```\n\n \n\n \n\n# Guide\n\n## Creating Transforms\n\nMost 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:\n\n```js\nRematrix.rotateZ(45)\n```\n\nThis returns a 45° rotation along the Z-axis, represented as an array of 16 values:\n\n```js\n[0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]\n```\n\nThese 16 values represent our **transformation matrix** in [column-major order](https://developer.mozilla.org/en-US/docs/Web/CSS/transform-function/matrix3d).\n\n \n\n## Combining Transforms (Using Multiplication)\n\nWhere 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:\n\n```js\nlet r1 = Rematrix.rotateZ(20)\nlet r2 = Rematrix.rotateZ(25)\n\nlet product = Rematrix.multiply(r1, r2)\n```\n\nHere `product` describes the same array of 16 values (seen above):\n\n```js\n[0.707107, 0.707107, 0, 0, -0.707107, 0.707107, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]\n```\n\n#### Better Multiplication (Using Reduce)\n\nThere’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:\n\n```js\nlet r1 = Rematrix.rotateZ(20)\nlet r2 = Rematrix.rotateZ(65)\nlet r3 = Rematrix.rotateZ(-40)\n\nlet product = [r1, r2, r3].reduce(Rematrix.multiply)\n```\n\n> Order is 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.\n\n## Preserving Transforms\n\nBefore applying any of our transforms, we should capture the existing transform of our element using `Rematrix.fromString()`, e.g:\n\n```js\nlet element = document.querySelector('#example')\nlet style = getComputedStyle(element).transform\n\nlet transform = Rematrix.fromString(style)\n\nlet r1 = Rematrix.rotateZ(20)\nlet r2 = Rematrix.rotateZ(65)\nlet r3 = Rematrix.rotateZ(-40)\n\nlet product = [transform, r1, r2, r3].reduce(Rematrix.multiply)\n```\n\nBy passing the computed transform styles to `Rematrix.fromString()`, we create a matrix of the existing transform. We can now factor this into our multiplication.\n\n> 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.\n\n## Applying Transforms\n\nWe can turn our matrix into valid CSS using `Rematrix.toString()`, which we can apply to our element’s style, e.g:\n\n```js\nelement.style.transform = Rematrix.toString(product)\n```\n\n#### _And that concludes this introduction to Rematrix. Please explore the finished [Live Demo on JSFiddle](https://jsfiddle.net/ufrLymvo/)._\n\n \n\n \n\n\n\n# API Reference\n\n* [format(source)](#Rematrix.format)\n* [fromString(source)](#Rematrix.fromString)\n* [identity()](#Rematrix.identity)\n* [inverse(source)](#Rematrix.inverse)\n* [multiply(matrixA, matrixB)](#Rematrix.multiply)\n* [perspective(distance)](#Rematrix.perspective)\n* [rotate(angle)](#Rematrix.rotate)\n* [rotateX(angle)](#Rematrix.rotateX)\n* [rotateY(angle)](#Rematrix.rotateY)\n* [rotateZ(angle)](#Rematrix.rotateZ)\n* [scale(scalar, [scalarY])](#Rematrix.scale)\n* [scaleX(scalar)](#Rematrix.scaleX)\n* [scaleY(scalar)](#Rematrix.scaleY)\n* [scaleZ(scalar)](#Rematrix.scaleZ)\n* [skew(angleX, [angleY])](#Rematrix.skew)\n* [skewX(angle)](#Rematrix.skewX)\n* [skewY(angle)](#Rematrix.skewY)\n* [toString(source)](#Rematrix.toString)\n* [translate(distanceX, [distanceY])](#Rematrix.translate)\n* [translate3d(distanceX, distanceY, distanceZ)](#Rematrix.translate3d)\n* [translateX(distance)](#Rematrix.translateX)\n* [translateY(distance)](#Rematrix.translateY)\n* [translateZ(distance)](#Rematrix.translateZ)\n\n\n\n \n### format(source) ⇒ `number[]`\n\nTransformation matrices in the browser come in two flavors:\n\n* `matrix` using 6 values (short)\n* `matrix3d` using 16 values (long)\n\nThis utility follows this [conversion guide](https://goo.gl/EJlUQ1)\nto expand short form matrices to their equivalent long form.\n\n| Param | Description |\n| ------ | -------------------------------- |\n| source | A `number[]` with length 6 or 16 |\n\n\n\n \n### fromString(source) ⇒ `number[]`\n\nConverts a CSS Transform to array.\n\n| Param | Description |\n| ------ | -------------------------------------------------------------- |\n| source | A `string` containing a `matrix` or `matrix3d` property value. |\n\n\n\n \n### identity() ⇒ `number[]`\n\nReturns a matrix representing no transformation. The product of any matrix\nmultiplied by the identity matrix will be the original matrix.\n\n> **Tip:** Similar to how `5 * 1 === 5`, where `1` is the identity.\n\n\n \n### inverse(source) ⇒ `number[]`\n\nReturns a matrix representing the inverse transformation of the source\nmatrix. The product of any matrix multiplied by its inverse will be the\nidentity matrix.\n\n> **Tip:** Similar to how `5 * (1/5) === 1`, where `1/5` is the inverse.\n\n| Param | Description |\n| ------ | -------------------------------- |\n| source | A `number[]` with length 6 or 16 |\n\n\n\n \n### multiply(matrixA, matrixB) ⇒ `number[]`\n\nReturns a matrix representing the combined transformations\nof both arguments.\n\n> **Note:** Order is important. For example, rotating 45° along the Z-axis,\n> followed by translating 500 pixels along the Y-axis...\n> Is not the same as translating 500 pixels along the Y-axis,\n> followed by rotating 45° along on the Z-axis.\n\n| Param | Description |\n| ------- | -------------------------------- |\n| matrixA | A `number[]` with length 6 or 16 |\n| matrixB | A `number[]` with length 6 or 16 |\n\n\n\n \n### perspective(distance) ⇒ `number[]`\n\nReturns a matrix representing perspective.\n\n| Param | Description |\n| -------- | ------------------------------ |\n| distance | A `number` measured in pixels. |\n\n\n\n \n### rotate(angle) ⇒ `number[]`\n\nReturns a matrix representing Z-axis rotation.\n\n> **Tip:** This is just an alias for `Rematrix.rotateZ` for parity with CSS\n\n| Param | Description |\n| ----- | ------------------------------- |\n| angle | A `number` measured in degrees. |\n\n\n\n \n### rotateX(angle) ⇒ `number[]`\n\nReturns a matrix representing X-axis rotation.\n\n| Param | Description |\n| ----- | ------------------------------- |\n| angle | A `number` measured in degrees. |\n\n\n\n \n### rotateY(angle) ⇒ `number[]`\n\nReturns a matrix representing Y-axis rotation.\n\n| Param | Description |\n| ----- | ------------------------------- |\n| angle | A `number` measured in degrees. |\n\n\n\n \n### rotateZ(angle) ⇒ `number[]`\n\nReturns a matrix representing Z-axis rotation.\n\n| Param | Description |\n| ----- | ------------------------------- |\n| angle | A `number` measured in degrees. |\n\n\n\n \n### scale(scalar, [scalarY]) ⇒ `number[]`\n\nReturns a matrix representing 2D scaling. The first argument\nis used for both X and Y-axis scaling, unless an optional\nsecond argument is provided to explicitly define Y-axis scaling.\n\n| Param | Description |\n| --------- | ----------------------------------------- |\n| scalar | A `number` decimal multiplier. |\n| [scalarY] | A `number` decimal multiplier. (Optional) |\n\n\n\n \n### scaleX(scalar) ⇒ `number[]`\n\nReturns a matrix representing X-axis scaling.\n\n| Param | Description |\n| ------ | ------------------------------ |\n| scalar | A `number` decimal multiplier. |\n\n\n\n \n### scaleY(scalar) ⇒ `number[]`\n\nReturns a matrix representing Y-axis scaling.\n\n| Param | Description |\n| ------ | ------------------------------ |\n| scalar | A `number` decimal multiplier. |\n\n\n\n \n### scaleZ(scalar) ⇒ `number[]`\n\nReturns a matrix representing Z-axis scaling.\n\n| Param | Description |\n| ------ | ------------------------------ |\n| scalar | A `number` decimal multiplier. |\n\n\n\n \n### skew(angleX, [angleY]) ⇒ `number[]`\n\nReturns a matrix representing shear. The first argument\ndefines X-axis shearing, and an optional second argument\ndefines Y-axis shearing.\n\n| Param | Description |\n| -------- | ------------------------------------------ |\n| angleX | A `number` measured in degrees. |\n| [angleY] | A `number` measured in degrees. (Optional) |\n\n\n\n \n### skewX(angle) ⇒ `number[]`\n\nReturns a matrix representing X-axis shear.\n\n| Param | Description |\n| ----- | ------------------------------- |\n| angle | A `number` measured in degrees. |\n\n\n\n \n### skewY(angle) ⇒ `number[]`\n\nReturns a matrix representing Y-axis shear.\n\n| Param | Description |\n| ----- | ------------------------------- |\n| angle | A `number` measured in degrees. |\n\n\n\n \n### toString(source) ⇒ `string`\n\nReturns a CSS Transform property value equivalent to the source matrix.\n\n| Param | Description |\n| ------ | -------------------------------- |\n| source | A `number[]` with length 6 or 16 |\n\n\n\n \n### translate(distanceX, [distanceY]) ⇒ `number[]`\n\nReturns a matrix representing 2D translation. The first\nargument defines X-axis translation, and an optional second\nargument defines Y-axis translation.\n\n| Param | Description |\n| ----------- | ----------------------------------------- |\n| distanceX | A `number` measured in pixels. |\n| [distanceY] | A `number` measured in pixels. (Optional) |\n\n\n\n \n### translate3d(distanceX, distanceY, distanceZ) ⇒ `number[]`\n\nReturns a matrix representing 3D translation. The first\nargument defines X-axis translation, the second argument defines Y-axis\ntranslation, and the third argument defines Z-axis translation.\n\n| Param | Description |\n| ----------| ------------------------------ |\n| distanceX | A `number` measured in pixels. |\n| distanceY | A `number` measured in pixels. |\n| distanceZ | A `number` measured in pixels. |\n\n\n\n \n### translateX(distance) ⇒ `number[]`\n\nReturns a matrix representing X-axis translation.\n\n| Param | Description |\n| -------- | ------------------------------ |\n| distance | A `number` measured in pixels. |\n\n\n\n \n### translateY(distance) ⇒ `number[]`\n\nReturns a matrix representing Y-axis translation.\n\n| Param | Description |\n| -------- | ------------------------------ |\n| distance | A `number` measured in pixels. |\n\n\n\n \n### translateZ(distance) ⇒ `number[]`\n\nReturns a matrix representing Z-axis translation.\n\n| Param | Description |\n| -------- | ------------------------------ |\n| distance | A `number` measured in pixels. |\n\n \n\n \n\n---\n\nCopyright 2021 Julian Lloyd.\n \nOpen source under the [MIT License](https://github.com/jlmakes/rematrix/blob/master/LICENSE).\n","maintainers":[{"name":"jlmakes","email":"julianlloyd@gmail.com"}],"time":{"modified":"2022-06-26T11:04:47.473Z","created":"2017-05-25T02:07:11.360Z","0.1.0":"2017-05-25T02:07:11.360Z","0.1.1":"2017-05-30T20:39:17.513Z","0.1.2":"2017-07-30T00:14:33.551Z","0.1.3":"2017-08-24T22:13:18.542Z","0.2.0":"2017-09-22T02:57:10.399Z","0.2.1":"2017-10-08T14:08:18.019Z","0.2.2":"2018-01-04T23:03:24.048Z","0.2.3":"2018-08-14T19:05:59.593Z","0.3.0":"2018-08-31T04:41:23.249Z","0.4.0":"2019-07-04T20:02:43.314Z","0.4.1":"2019-07-05T16:29:49.494Z","0.5.0-canary.1":"2020-01-04T04:16:16.359Z","0.5.0":"2020-03-03T00:16:21.818Z","0.6.0":"2020-05-04T08:17:40.689Z","0.7.0":"2020-05-04T08:38:14.801Z","0.7.1":"2020-12-31T22:56:33.809Z","0.7.2":"2021-02-17T10:58:04.003Z"},"homepage":"https://github.com/jlmakes/rematrix#readme","keywords":["css","matrix","transform"],"repository":{"type":"git","url":"git+https://github.com/jlmakes/rematrix.git"},"author":{"name":"Julian Lloyd","email":"rematrix@jlmakes.com"},"bugs":{"url":"https://github.com/jlmakes/rematrix/issues"},"license":"MIT","readmeFilename":"README.md"}
![](\"https://jlmakes.com/logos/svg/rematrix.svg\")
\n \n![\"Rematrix\"](\"https://jlmakes.com/logos/svg/rematrix-logotype.svg\")
\n \n![\"Build](\"https://img.shields.io/travis/jlmakes/rematrix.svg\")
\n\t![\"Coverage\"](\"https://img.shields.io/coveralls/jlmakes/rematrix.svg\")
\n\t![\"Downloads\"](\"https://img.shields.io/npm/dm/rematrix.svg\")
\n\t![\"Version\"](\"https://img.shields.io/npm/v/rematrix.svg\")
\n ![\"1.3](\"https://img.shields.io/badge/min+gzip-1.3_kB-blue.svg\"){kind=icon}
\n\t![\"MIT](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n![\"Browser](\"https://saucelabs.com/browser-matrix/rematrix.svg\")
\n\t\n