0
# Transform System
1

2
Web-specific transform handling with optimized CSS transform generation and shorthand properties. The transform system automatically handles unit conversion, combines transforms efficiently, and optimizes for performance.
3

4
## Capabilities
5

6
### Transform Properties
7

8
Extended CSS transform properties with automatic unit handling and optimization.
9

10
```typescript { .api }
11
interface TransformProps {
12
  /** Transform string (overrides all other transform properties) */
13
  transform?: string;
14
  
15
  /** Translation shortcuts */
16
  x?: Length;
17
  y?: Length;
18
  z?: Length;
19
  
20
  /** Standard translation properties */
21
  translate?: Length | readonly [Length, Length];
22
  translateX?: Length;
23
  translateY?: Length;
24
  translateZ?: Length;
25
  translate3d?: readonly [Length, Length, Length];
26
  
27
  /** Rotation properties */
28
  rotate?: Angle;
29
  rotateX?: Angle;
30
  rotateY?: Angle;
31
  rotateZ?: Angle;
32
  rotate3d?: readonly [number, number, number, Angle];
33
  
34
  /** Scale properties */
35
  scale?: number | readonly [number, number] | string;
36
  scaleX?: number;
37
  scaleY?: number;
38
  scaleZ?: number;
39
  scale3d?: readonly [number, number, number];
40
  
41
  /** Skew properties */
42
  skew?: Angle | readonly [Angle, Angle];
43
  skewX?: Angle;
44
  skewY?: Angle;
45
  
46
  /** Matrix transformations */
47
  matrix?: readonly [number, number, number, number, number, number];
48
  matrix3d?: readonly [
49
    number, number, number, number,
50
    number, number, number, number,
51
    number, number, number, number,
52
    number, number, number, number
53
  ];
54
}
55

56
type Length = number | string;
57
type Angle = number | string;
58
```
59

60
**Usage Examples:**
61

62
```typescript
63
import { useSpring, animated } from "@react-spring/web";
64

65
function TransformDemo() {
66
  const styles = useSpring({
67
    from: {
68
      x: 0,
69
      y: 0,
70
      rotate: 0,
71
      scale: 0.8,
72
    },
73
    to: {
74
      x: 100,
75
      y: 50,
76
      rotate: 45,
77
      scale: 1,
78
    },
79
  });
80

81
  return <animated.div style={styles}>Transformed element</animated.div>;
82
}
83

84
// Advanced transform combinations
85
function AdvancedTransforms() {
86
  const styles = useSpring({
87
    from: {
88
      translateX: '0px',
89
      rotateZ: '0deg',
90
      scaleX: 1,
91
      scaleY: 1,
92
    },
93
    to: {
94
      translateX: '200px',
95
      rotateZ: '180deg',
96
      scaleX: 1.5,
97
      scaleY: 0.8,
98
    },
99
  });
100

101
  return <animated.div style={styles}>Complex transforms</animated.div>;
102
}
103
```
104

105
### Automatic Unit Addition
106

107
The transform system automatically adds appropriate units to numeric values.
108

109
```typescript { .api }
110
interface UnitRules {
111
  /** Translation properties get 'px' units by default */
112
  translation: 'px';
113
  /** Rotation and skew properties get 'deg' units by default */
114
  rotation: 'deg';
115
  /** Scale properties are unitless */
116
  scale: 'unitless';
117
}
118
```
119

120
**Transform Unit Examples:**
121

122
```typescript
123
// These are equivalent:
124
const styles1 = useSpring({
125
  x: 100,        // Becomes '100px'
126
  rotate: 45,    // Becomes '45deg'
127
  scale: 1.2,    // Remains 1.2 (unitless)
128
});
129

130
const styles2 = useSpring({
131
  x: '100px',
132
  rotate: '45deg',
133
  scale: 1.2,
134
});
135
```
136

137
### Transform Optimization
138

139
The system optimizes transforms by combining similar operations and detecting identity transforms.
140

141
```typescript { .api }
142
interface TransformOptimization {
143
  /** Combines x, y, z into single translate3d() */
144
  translation: 'translate3d(x, y, z)';
145
  /** Identity transforms become 'none' */
146
  identity: 'none';
147
  /** Similar transforms are combined efficiently */
148
  combination: 'optimized';
149
}
150
```
151

152
**Optimization Examples:**
153

154
```typescript
155
// x, y, z are combined into translate3d
156
const styles = useSpring({
157
  x: 50,    // \
158
  y: 100,   //  > Combined into: translate3d(50px, 100px, 0px)
159
  z: 0,     // /
160
  rotate: 0, // Identity rotation is optimized out
161
});
162

163
// Results in: transform: translate3d(50px, 100px, 0px)
164
```
165

166
### AnimatedStyle Class
167

168
Internal class handling CSS transform processing and optimization.
169

170
```typescript { .api }
171
/**
172
 * Specialized AnimatedObject for handling CSS transforms
173
 * Automatically processes x, y, z shortcuts and optimizes transform strings
174
 */
175
class AnimatedStyle extends AnimatedObject {
176
  constructor(style: StyleProps & TransformProps): AnimatedStyle;
177
}
178

179
interface StyleProps extends CSSProperties, TransformProps {
180
  [key: string]: any;
181
}
182
```
183

184
### Transform Processing
185

186
How different transform properties are processed internally.
187

188
```typescript { .api }
189
interface TransformProcessing {
190
  /** Shorthand properties (x, y, z) */
191
  shortcuts: {
192
    /** Combined into translate3d for optimal performance */
193
    xyz: 'translate3d(x, y, z)';
194
  };
195
  
196
  /** Standard transform functions */
197
  functions: {
198
    translate: '(value)' | '(x, y)';
199
    translateX: '(value)';
200
    translateY: '(value)';
201
    translateZ: '(value)';
202
    translate3d: '(x, y, z)';
203
    rotate: '(angle)';
204
    rotateX: '(angle)';
205
    rotateY: '(angle)';
206
    rotateZ: '(angle)';
207
    rotate3d: '(x, y, z, angle)';
208
    scale: '(value)' | '(x, y)';
209
    scaleX: '(value)';
210
    scaleY: '(value)';
211
    scaleZ: '(value)';
212
    scale3d: '(x, y, z)';
213
    skew: '(angle)' | '(x, y)';
214
    skewX: '(angle)';
215
    skewY: '(angle)';
216
    matrix: '(a, b, c, d, e, f)';
217
    matrix3d: '(a1, b1, c1, d1, a2, b2, c2, d2, a3, b3, c3, d3, a4, b4, c4, d4)';
218
  };
219
}
220
```
221

222
### Performance Considerations
223

224
Transform system optimizations for better animation performance.
225

226
```typescript { .api }
227
interface PerformanceOptimizations {
228
  /** Use translate3d to trigger hardware acceleration */
229
  hardware_acceleration: 'translate3d()';
230
  
231
  /** Combine transforms to minimize reflows */
232
  transform_combination: 'single_transform_property';
233
  
234
  /** Optimize identity transforms */
235
  identity_detection: 'none_for_identity';
236
  
237
  /** Efficient unit addition */
238
  unit_processing: 'automatic_px_deg_addition';
239
}
240
```
241

242
**Performance Best Practices:**
243

244
```typescript
245
// Good: Uses shortcuts that combine into translate3d
246
const efficientStyles = useSpring({
247
  x: targetX,
248
  y: targetY,
249
  rotate: targetRotation,
250
});
251

252
// Less efficient: Separate transform functions
253
const lessEfficientStyles = useSpring({
254
  translateX: targetX,
255
  translateY: targetY,
256
  rotateZ: targetRotation,
257
});
258

259
// Good: Single transform string for complex cases
260
const complexStyles = useSpring({
261
  transform: 'translate3d(100px, 50px, 0) rotate(45deg) scale(1.2)',
262
});
263
```
264

265
### Identity Transform Detection
266

267
The system detects when transforms have no visual effect and optimizes them.
268

269
```typescript { .api }
270
interface IdentityValues {
271
  /** Translation identity values */
272
  translation: 0;
273
  /** Rotation identity values */
274
  rotation: 0;
275
  /** Scale identity values */
276
  scale: 1;
277
  /** Skew identity values */
278
  skew: 0;
279
}
280
```
281

282
**Identity Detection Examples:**
283

284
```typescript
285
// These result in transform: none (optimized out)
286
const identityStyles = useSpring({
287
  x: 0,
288
  y: 0,
289
  rotate: 0,
290
  scale: 1,
291
});
292

293
// Mixed identity and non-identity
294
const mixedStyles = useSpring({
295
  x: 100,      // Applied
296
  y: 0,        // Part of translate3d but with 0 value
297
  rotate: 0,   // Optimized out (identity)
298
  scale: 1,    // Optimized out (identity)
299
});
300
// Results in: transform: translate3d(100px, 0px, 0px)
301
```
302

303
### Custom Transform Strings
304

305
When you need complete control over transforms, use the transform property directly.
306

307
```typescript { .api }
308
interface CustomTransforms {
309
  /** Direct transform string bypasses all processing */
310
  transform: string;
311
}
312
```
313

314
**Custom Transform Examples:**
315

316
```typescript
317
// Custom transform string
318
const customStyles = useSpring({
319
  transform: 'perspective(1000px) rotateX(45deg) translateZ(100px)',
320
});
321

322
// Interpolated custom transforms
323
const interpolatedStyles = useSpring({
324
  transform: progress => `rotate(${progress * 360}deg) scale(${1 + progress * 0.5})`,
325
});
326
```