From 37be8eac20060928cb3ba4e8175cea158c35464c Mon Sep 17 00:00:00 2001 From: AbhishekGiri04 Date: Tue, 16 Dec 2025 23:42:51 +0530 Subject: [PATCH 1/2] docs: Add matrix transform documentation and example Fixes #1899 Added comprehensive documentation for the matrix transform property which was previously undocumented despite being supported in React Native. Changes: - Added matrix transform example in the interactive demo - Documented the 4x4 matrix structure and column-major order - Provided practical examples of matrix usage - Added note about when to use matrix vs individual transforms - Clarified that matrix is useful for UI editors and pre-calculated transforms This addresses the confusion around the deprecated transformMatrix property and provides clear guidance on using the modern matrix syntax. --- docs/transforms.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/transforms.md b/docs/transforms.md index 9bf22dcaa9f..9eb6ed2b0bd 100644 --- a/docs/transforms.md +++ b/docs/transforms.md @@ -129,6 +129,20 @@ const App = () => ( ]}> TranslateY by 50 + + + Matrix Transform + @@ -195,6 +209,43 @@ The skew transformations require a string so that the transform may be expressed } ``` +### Matrix Transform + +The `matrix` transform accepts a 4x4 transformation matrix as an array of 16 numbers. This allows you to apply complex transformations that combine translation, rotation, scaling, and skewing in a single operation. + +The matrix is specified in column-major order: + +```js +{ + transform: [ + { + matrix: [ + scaleX, skewY, 0, 0, + skewX, scaleY, 0, 0, + 0, 0, 1, 0, + translateX, translateY, 0, 1 + ] + } + ] +} +``` + +For example, to apply a combination of scale and skew: + +```js +{ + transform: [ + { + matrix: [1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] + } + ] +} +``` + +:::note +Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For simple transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. +::: + | Type | Required | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | array of objects: `{matrix: number[]}`, `{perspective: number}`, `{rotate: string}`, `{rotateX: string}`, `{rotateY: string}`, `{rotateZ: string}`, `{scale: number}`, `{scaleX: number}`, `{scaleY: number}`, `{translateX: number}`, `{translateY: number}`, `{skewX: string}`, `{skewY: string}` or string | No | From 83b1f25d0bc10dffdde87bedfde0483ac28c20f7 Mon Sep 17 00:00:00 2001 From: AbhishekGiri04 Date: Wed, 17 Dec 2025 16:12:47 +0530 Subject: [PATCH 2/2] Add matrix transform docs to versioned docs and fix lint issues --- docs/transforms.md | 36 ++++++--- .../versioned_docs/version-0.77/transforms.md | 78 +++++++++++++++++-- .../versioned_docs/version-0.78/transforms.md | 78 +++++++++++++++++-- .../versioned_docs/version-0.79/transforms.md | 78 +++++++++++++++++-- .../versioned_docs/version-0.80/transforms.md | 78 +++++++++++++++++-- .../versioned_docs/version-0.81/transforms.md | 76 ++++++++++++++++-- .../versioned_docs/version-0.82/transforms.md | 65 ++++++++++++++++ .../versioned_docs/version-0.83/transforms.md | 65 ++++++++++++++++ 8 files changed, 504 insertions(+), 50 deletions(-) diff --git a/docs/transforms.md b/docs/transforms.md index 9eb6ed2b0bd..e0576ae8101 100644 --- a/docs/transforms.md +++ b/docs/transforms.md @@ -220,13 +220,25 @@ The matrix is specified in column-major order: transform: [ { matrix: [ - scaleX, skewY, 0, 0, - skewX, scaleY, 0, 0, - 0, 0, 1, 0, - translateX, translateY, 0, 1 - ] - } - ] + scaleX, + skewY, + 0, + 0, + skewX, + scaleY, + 0, + 0, + 0, + 0, + 1, + 0, + translateX, + translateY, + 0, + 1, + ], + }, + ]; } ``` @@ -236,14 +248,16 @@ For example, to apply a combination of scale and skew: { transform: [ { - matrix: [1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1] - } - ] + matrix: [ + 1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, + ], + }, + ]; } ``` :::note -Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For simple transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. +Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For basic transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. ::: | Type | Required | diff --git a/website/versioned_docs/version-0.77/transforms.md b/website/versioned_docs/version-0.77/transforms.md index c1fc1fc04b6..e0576ae8101 100644 --- a/website/versioned_docs/version-0.77/transforms.md +++ b/website/versioned_docs/version-0.77/transforms.md @@ -129,6 +129,20 @@ const App = () => ( ]}> TranslateY by 50 + + + Matrix Transform + @@ -195,6 +209,57 @@ The skew transformations require a string so that the transform may be expressed } ``` +### Matrix Transform + +The `matrix` transform accepts a 4x4 transformation matrix as an array of 16 numbers. This allows you to apply complex transformations that combine translation, rotation, scaling, and skewing in a single operation. + +The matrix is specified in column-major order: + +```js +{ + transform: [ + { + matrix: [ + scaleX, + skewY, + 0, + 0, + skewX, + scaleY, + 0, + 0, + 0, + 0, + 1, + 0, + translateX, + translateY, + 0, + 1, + ], + }, + ]; +} +``` + +For example, to apply a combination of scale and skew: + +```js +{ + transform: [ + { + matrix: [ + 1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, + ], + }, + ]; +} +``` + +:::note +Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For basic transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. +::: + | Type | Required | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | array of objects: `{matrix: number[]}`, `{perspective: number}`, `{rotate: string}`, `{rotateX: string}`, `{rotateY: string}`, `{rotateZ: string}`, `{scale: number}`, `{scaleX: number}`, `{scaleY: number}`, `{translateX: number}`, `{translateY: number}`, `{skewX: string}`, `{skewY: string}` or string | No | @@ -203,7 +268,9 @@ The skew transformations require a string so that the transform may be expressed ### `decomposedMatrix`, `rotation`, `scaleX`, `scaleY`, `transformMatrix`, `translateX`, `translateY` -> **Deprecated.** Use the [`transform`](transforms#transform) prop instead. +:::warning Deprecated +Use the [`transform`](transforms#transform) prop instead. +::: ## Transform Origin @@ -211,14 +278,9 @@ The `transformOrigin` property sets the origin for a view's transformations. The # Example -```SnackPlayer name=TransformOrigin%20Example&supportedPlatforms=ios,android +```SnackPlayer name=TransformOrigin%20Example import React, {useEffect, useRef} from 'react'; -import { - Animated, - View, - StyleSheet, - Easing, -} from 'react-native'; +import {Animated, View, StyleSheet, Easing} from 'react-native'; import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context'; const App = () => { diff --git a/website/versioned_docs/version-0.78/transforms.md b/website/versioned_docs/version-0.78/transforms.md index c1fc1fc04b6..e0576ae8101 100644 --- a/website/versioned_docs/version-0.78/transforms.md +++ b/website/versioned_docs/version-0.78/transforms.md @@ -129,6 +129,20 @@ const App = () => ( ]}> TranslateY by 50 + + + Matrix Transform + @@ -195,6 +209,57 @@ The skew transformations require a string so that the transform may be expressed } ``` +### Matrix Transform + +The `matrix` transform accepts a 4x4 transformation matrix as an array of 16 numbers. This allows you to apply complex transformations that combine translation, rotation, scaling, and skewing in a single operation. + +The matrix is specified in column-major order: + +```js +{ + transform: [ + { + matrix: [ + scaleX, + skewY, + 0, + 0, + skewX, + scaleY, + 0, + 0, + 0, + 0, + 1, + 0, + translateX, + translateY, + 0, + 1, + ], + }, + ]; +} +``` + +For example, to apply a combination of scale and skew: + +```js +{ + transform: [ + { + matrix: [ + 1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, + ], + }, + ]; +} +``` + +:::note +Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For basic transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. +::: + | Type | Required | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | array of objects: `{matrix: number[]}`, `{perspective: number}`, `{rotate: string}`, `{rotateX: string}`, `{rotateY: string}`, `{rotateZ: string}`, `{scale: number}`, `{scaleX: number}`, `{scaleY: number}`, `{translateX: number}`, `{translateY: number}`, `{skewX: string}`, `{skewY: string}` or string | No | @@ -203,7 +268,9 @@ The skew transformations require a string so that the transform may be expressed ### `decomposedMatrix`, `rotation`, `scaleX`, `scaleY`, `transformMatrix`, `translateX`, `translateY` -> **Deprecated.** Use the [`transform`](transforms#transform) prop instead. +:::warning Deprecated +Use the [`transform`](transforms#transform) prop instead. +::: ## Transform Origin @@ -211,14 +278,9 @@ The `transformOrigin` property sets the origin for a view's transformations. The # Example -```SnackPlayer name=TransformOrigin%20Example&supportedPlatforms=ios,android +```SnackPlayer name=TransformOrigin%20Example import React, {useEffect, useRef} from 'react'; -import { - Animated, - View, - StyleSheet, - Easing, -} from 'react-native'; +import {Animated, View, StyleSheet, Easing} from 'react-native'; import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context'; const App = () => { diff --git a/website/versioned_docs/version-0.79/transforms.md b/website/versioned_docs/version-0.79/transforms.md index c1fc1fc04b6..e0576ae8101 100644 --- a/website/versioned_docs/version-0.79/transforms.md +++ b/website/versioned_docs/version-0.79/transforms.md @@ -129,6 +129,20 @@ const App = () => ( ]}> TranslateY by 50 + + + Matrix Transform + @@ -195,6 +209,57 @@ The skew transformations require a string so that the transform may be expressed } ``` +### Matrix Transform + +The `matrix` transform accepts a 4x4 transformation matrix as an array of 16 numbers. This allows you to apply complex transformations that combine translation, rotation, scaling, and skewing in a single operation. + +The matrix is specified in column-major order: + +```js +{ + transform: [ + { + matrix: [ + scaleX, + skewY, + 0, + 0, + skewX, + scaleY, + 0, + 0, + 0, + 0, + 1, + 0, + translateX, + translateY, + 0, + 1, + ], + }, + ]; +} +``` + +For example, to apply a combination of scale and skew: + +```js +{ + transform: [ + { + matrix: [ + 1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, + ], + }, + ]; +} +``` + +:::note +Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For basic transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. +::: + | Type | Required | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | array of objects: `{matrix: number[]}`, `{perspective: number}`, `{rotate: string}`, `{rotateX: string}`, `{rotateY: string}`, `{rotateZ: string}`, `{scale: number}`, `{scaleX: number}`, `{scaleY: number}`, `{translateX: number}`, `{translateY: number}`, `{skewX: string}`, `{skewY: string}` or string | No | @@ -203,7 +268,9 @@ The skew transformations require a string so that the transform may be expressed ### `decomposedMatrix`, `rotation`, `scaleX`, `scaleY`, `transformMatrix`, `translateX`, `translateY` -> **Deprecated.** Use the [`transform`](transforms#transform) prop instead. +:::warning Deprecated +Use the [`transform`](transforms#transform) prop instead. +::: ## Transform Origin @@ -211,14 +278,9 @@ The `transformOrigin` property sets the origin for a view's transformations. The # Example -```SnackPlayer name=TransformOrigin%20Example&supportedPlatforms=ios,android +```SnackPlayer name=TransformOrigin%20Example import React, {useEffect, useRef} from 'react'; -import { - Animated, - View, - StyleSheet, - Easing, -} from 'react-native'; +import {Animated, View, StyleSheet, Easing} from 'react-native'; import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context'; const App = () => { diff --git a/website/versioned_docs/version-0.80/transforms.md b/website/versioned_docs/version-0.80/transforms.md index c1fc1fc04b6..e0576ae8101 100644 --- a/website/versioned_docs/version-0.80/transforms.md +++ b/website/versioned_docs/version-0.80/transforms.md @@ -129,6 +129,20 @@ const App = () => ( ]}> TranslateY by 50 + + + Matrix Transform + @@ -195,6 +209,57 @@ The skew transformations require a string so that the transform may be expressed } ``` +### Matrix Transform + +The `matrix` transform accepts a 4x4 transformation matrix as an array of 16 numbers. This allows you to apply complex transformations that combine translation, rotation, scaling, and skewing in a single operation. + +The matrix is specified in column-major order: + +```js +{ + transform: [ + { + matrix: [ + scaleX, + skewY, + 0, + 0, + skewX, + scaleY, + 0, + 0, + 0, + 0, + 1, + 0, + translateX, + translateY, + 0, + 1, + ], + }, + ]; +} +``` + +For example, to apply a combination of scale and skew: + +```js +{ + transform: [ + { + matrix: [ + 1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, + ], + }, + ]; +} +``` + +:::note +Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For basic transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. +::: + | Type | Required | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | array of objects: `{matrix: number[]}`, `{perspective: number}`, `{rotate: string}`, `{rotateX: string}`, `{rotateY: string}`, `{rotateZ: string}`, `{scale: number}`, `{scaleX: number}`, `{scaleY: number}`, `{translateX: number}`, `{translateY: number}`, `{skewX: string}`, `{skewY: string}` or string | No | @@ -203,7 +268,9 @@ The skew transformations require a string so that the transform may be expressed ### `decomposedMatrix`, `rotation`, `scaleX`, `scaleY`, `transformMatrix`, `translateX`, `translateY` -> **Deprecated.** Use the [`transform`](transforms#transform) prop instead. +:::warning Deprecated +Use the [`transform`](transforms#transform) prop instead. +::: ## Transform Origin @@ -211,14 +278,9 @@ The `transformOrigin` property sets the origin for a view's transformations. The # Example -```SnackPlayer name=TransformOrigin%20Example&supportedPlatforms=ios,android +```SnackPlayer name=TransformOrigin%20Example import React, {useEffect, useRef} from 'react'; -import { - Animated, - View, - StyleSheet, - Easing, -} from 'react-native'; +import {Animated, View, StyleSheet, Easing} from 'react-native'; import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context'; const App = () => { diff --git a/website/versioned_docs/version-0.81/transforms.md b/website/versioned_docs/version-0.81/transforms.md index a88c207ad7a..e0576ae8101 100644 --- a/website/versioned_docs/version-0.81/transforms.md +++ b/website/versioned_docs/version-0.81/transforms.md @@ -129,6 +129,20 @@ const App = () => ( ]}> TranslateY by 50 + + + Matrix Transform + @@ -195,6 +209,57 @@ The skew transformations require a string so that the transform may be expressed } ``` +### Matrix Transform + +The `matrix` transform accepts a 4x4 transformation matrix as an array of 16 numbers. This allows you to apply complex transformations that combine translation, rotation, scaling, and skewing in a single operation. + +The matrix is specified in column-major order: + +```js +{ + transform: [ + { + matrix: [ + scaleX, + skewY, + 0, + 0, + skewX, + scaleY, + 0, + 0, + 0, + 0, + 1, + 0, + translateX, + translateY, + 0, + 1, + ], + }, + ]; +} +``` + +For example, to apply a combination of scale and skew: + +```js +{ + transform: [ + { + matrix: [ + 1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, + ], + }, + ]; +} +``` + +:::note +Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For basic transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. +::: + | Type | Required | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | array of objects: `{matrix: number[]}`, `{perspective: number}`, `{rotate: string}`, `{rotateX: string}`, `{rotateY: string}`, `{rotateZ: string}`, `{scale: number}`, `{scaleX: number}`, `{scaleY: number}`, `{translateX: number}`, `{translateY: number}`, `{skewX: string}`, `{skewY: string}` or string | No | @@ -203,7 +268,9 @@ The skew transformations require a string so that the transform may be expressed ### `decomposedMatrix`, `rotation`, `scaleX`, `scaleY`, `transformMatrix`, `translateX`, `translateY` -> **Deprecated.** Use the [`transform`](transforms#transform) prop instead. +:::warning Deprecated +Use the [`transform`](transforms#transform) prop instead. +::: ## Transform Origin @@ -213,12 +280,7 @@ The `transformOrigin` property sets the origin for a view's transformations. The ```SnackPlayer name=TransformOrigin%20Example import React, {useEffect, useRef} from 'react'; -import { - Animated, - View, - StyleSheet, - Easing, -} from 'react-native'; +import {Animated, View, StyleSheet, Easing} from 'react-native'; import {SafeAreaView, SafeAreaProvider} from 'react-native-safe-area-context'; const App = () => { diff --git a/website/versioned_docs/version-0.82/transforms.md b/website/versioned_docs/version-0.82/transforms.md index 9bf22dcaa9f..e0576ae8101 100644 --- a/website/versioned_docs/version-0.82/transforms.md +++ b/website/versioned_docs/version-0.82/transforms.md @@ -129,6 +129,20 @@ const App = () => ( ]}> TranslateY by 50 + + + Matrix Transform + @@ -195,6 +209,57 @@ The skew transformations require a string so that the transform may be expressed } ``` +### Matrix Transform + +The `matrix` transform accepts a 4x4 transformation matrix as an array of 16 numbers. This allows you to apply complex transformations that combine translation, rotation, scaling, and skewing in a single operation. + +The matrix is specified in column-major order: + +```js +{ + transform: [ + { + matrix: [ + scaleX, + skewY, + 0, + 0, + skewX, + scaleY, + 0, + 0, + 0, + 0, + 1, + 0, + translateX, + translateY, + 0, + 1, + ], + }, + ]; +} +``` + +For example, to apply a combination of scale and skew: + +```js +{ + transform: [ + { + matrix: [ + 1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, + ], + }, + ]; +} +``` + +:::note +Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For basic transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. +::: + | Type | Required | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | array of objects: `{matrix: number[]}`, `{perspective: number}`, `{rotate: string}`, `{rotateX: string}`, `{rotateY: string}`, `{rotateZ: string}`, `{scale: number}`, `{scaleX: number}`, `{scaleY: number}`, `{translateX: number}`, `{translateY: number}`, `{skewX: string}`, `{skewY: string}` or string | No | diff --git a/website/versioned_docs/version-0.83/transforms.md b/website/versioned_docs/version-0.83/transforms.md index 9bf22dcaa9f..e0576ae8101 100644 --- a/website/versioned_docs/version-0.83/transforms.md +++ b/website/versioned_docs/version-0.83/transforms.md @@ -129,6 +129,20 @@ const App = () => ( ]}> TranslateY by 50 + + + Matrix Transform + @@ -195,6 +209,57 @@ The skew transformations require a string so that the transform may be expressed } ``` +### Matrix Transform + +The `matrix` transform accepts a 4x4 transformation matrix as an array of 16 numbers. This allows you to apply complex transformations that combine translation, rotation, scaling, and skewing in a single operation. + +The matrix is specified in column-major order: + +```js +{ + transform: [ + { + matrix: [ + scaleX, + skewY, + 0, + 0, + skewX, + scaleY, + 0, + 0, + 0, + 0, + 1, + 0, + translateX, + translateY, + 0, + 1, + ], + }, + ]; +} +``` + +For example, to apply a combination of scale and skew: + +```js +{ + transform: [ + { + matrix: [ + 1, 0.5, 0, 0, 0.5, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, + ], + }, + ]; +} +``` + +:::note +Matrix transforms are useful when you need to apply pre-calculated transformation matrices, such as those from animation libraries or when building UI editor applications. For basic transformations, it's recommended to use the individual transform properties (scale, rotate, translate, etc.) as they are more readable. +::: + | Type | Required | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | | array of objects: `{matrix: number[]}`, `{perspective: number}`, `{rotate: string}`, `{rotateX: string}`, `{rotateY: string}`, `{rotateZ: string}`, `{scale: number}`, `{scaleX: number}`, `{scaleY: number}`, `{translateX: number}`, `{translateY: number}`, `{skewX: string}`, `{skewY: string}` or string | No |