0
# @react-spring/web
1

2
@react-spring/web provides React DOM-specific implementation of the react-spring animation library, enabling spring-physics based animations for web applications. It serves as the web target for the cross-platform react-spring ecosystem, offering animated components and hooks that integrate seamlessly with React DOM.
3

4
## Package Information
5

6
- **Package Name**: @react-spring/web  
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @react-spring/web`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  animated, 
16
  useSpring, 
17
  useTransition, 
18
  useScroll,
19
  useResize,
20
  useInView,
21
  Spring,
22
  Trail,
23
  Transition,
24
  Controller,
25
  SpringValue,
26
  to,
27
  config 
28
} from "@react-spring/web";
29
```
30

31
For CommonJS:
32

33
```javascript
34
const { 
35
  animated, 
36
  useSpring, 
37
  useTransition, 
38
  useScroll,
39
  useResize,
40
  useInView,
41
  Spring,
42
  Trail,
43
  Transition,
44
  Controller,
45
  SpringValue,
46
  to,
47
  config 
48
} = require("@react-spring/web");
49
```
50

51
## Basic Usage
52

53
```typescript
54
import { animated, useSpring, useTransition } from "@react-spring/web";
55

56
// Simple spring animation
57
function FadeBox() {
58
  const styles = useSpring({
59
    from: { opacity: 0 },
60
    to: { opacity: 1 },
61
  });
62

63
  return <animated.div style={styles}>Hello World</animated.div>;
64
}
65

66
// List transitions
67
function TodoList({ items }) {
68
  const transitions = useTransition(items, {
69
    from: { opacity: 0, transform: 'translateY(-20px)' },
70
    enter: { opacity: 1, transform: 'translateY(0px)' },
71
    leave: { opacity: 0, transform: 'translateY(-20px)' },
72
  });
73

74
  return transitions((style, item) => (
75
    <animated.div style={style}>{item.text}</animated.div>
76
  ));
77
}
78
```
79

80
## Architecture
81

82
@react-spring/web is built around several key components:
83

84
- **Animated Components**: DOM-specific animated primitives for HTML and SVG elements
85
- **Animation Hooks**: React hooks providing declarative animation control
86
- **Transform System**: Specialized CSS transform handling with optimizations
87
- **Value Application**: Direct DOM manipulation for optimal performance
88
- **Spring Physics**: Natural motion curves based on physical principles
89

90
## Capabilities
91

92
### Animated Components
93

94
Core animated DOM elements supporting all HTML and SVG tags with spring-powered animations.
95

96
```typescript { .api }
97
const animated: {
98
  <T extends ElementType>(component: T): AnimatedComponent<T>;
99
} & {
100
  [Tag in keyof JSX.IntrinsicElements]: AnimatedComponent<Tag>;
101
};
102

103
const a: typeof animated;
104
```
105

106
[Animated Components](./animated-components.md)
107

108
### Animation Hooks
109

110
React hooks for declarative animation control including springs, transitions, trails, and utility hooks.
111

112
```typescript { .api }
113
function useSpring<Props extends object>(
114
  props: UseSpringProps<Props>
115
): SpringValues<PickAnimated<Props>>;
116

117
function useTransition<Item, Props extends object>(
118
  data: OneOrMore<Item>,
119
  props: UseTransitionProps<Item, Props>
120
): TransitionFn<Item, PickAnimated<Props>>;
121

122
function useTrail<Props extends object>(
123
  length: number,
124
  props: UseTrailProps<Props>
125
): SpringValues<PickAnimated<Props>>[];
126
```
127

128
[Animation Hooks](./animation-hooks.md)
129

130
### Transform System
131

132
Web-specific transform handling with optimized CSS transform generation and shorthand properties.
133

134
```typescript { .api }
135
interface TransformProps {
136
  x?: Length;
137
  y?: Length;
138
  z?: Length;
139
  rotate?: Angle;
140
  scale?: number | readonly [number, number];
141
  transform?: string;
142
  translateX?: Length;
143
  translateY?: Length;
144
  translateZ?: Length;
145
  rotateX?: Angle;
146
  rotateY?: Angle;
147
  rotateZ?: Angle;
148
  scaleX?: number;
149
  scaleY?: number;
150
  scaleZ?: number;
151
}
152
```
153

154
[Transform System](./transform-system.md)
155

156
### Imperative Control
157

158
Classes and utilities for imperative animation control and advanced use cases.
159

160
```typescript { .api }
161
class Controller<State extends Lookup = Lookup> {
162
  start(props?: ControllerUpdate<State>): Promise<AnimationResult<State>>;
163
  stop(keys?: OneOrMore<string>): this;
164
  update(props: ControllerUpdate<State>): this;
165
}
166

167
class SpringValue<T = any> extends FrameValue<T> {
168
  start(props?: SpringUpdate<T>): Promise<AnimationResult<SpringValue<T>>>;
169
  stop(): this;
170
  set(value: T | FluidValue<T>): this;
171
}
172
```
173

174
[Imperative Control](./imperative-control.md)
175

176
### Declarative Components
177

178
React components providing declarative animation control with render props pattern.
179

180
```typescript { .api }
181
/**
182
 * Declarative spring animation component
183
 * @param props - Spring configuration with children render prop
184
 * @returns JSX element from children function
185
 */
186
function Spring<State extends object>(
187
  props: SpringComponentProps<State>
188
): JSX.Element | null;
189

190
/**
191
 * Declarative trail animation component for staggered animations
192
 * @param props - Trail configuration with items and children render prop
193
 * @returns JSX element from children function
194
 */
195
function Trail<Item, Props extends object>(
196
  props: TrailComponentProps<Item, Props>
197
): JSX.Element | null;
198

199
/**
200
 * Declarative transition animation component for entering/leaving items
201
 * @param props - Transition configuration with items and children render prop
202
 * @returns JSX element from children function
203
 */
204
function Transition<Item, Props extends object>(
205
  props: TransitionComponentProps<Item, Props>
206
): JSX.Element;
207

208
interface SpringComponentProps<State extends object> extends UseSpringProps<State> {
209
  /** Render prop function receiving spring values */
210
  children: (values: SpringValues<State>) => React.JSX.Element | null;
211
}
212

213
interface TrailComponentProps<Item, Props extends object> extends UseSpringProps<Props> {
214
  /** Array of items to animate */
215
  items: readonly Item[];
216
  /** Render prop function for each item with spring values */
217
  children: (
218
    item: Item,
219
    index: number
220
  ) => ((values: SpringValues<PickAnimated<Props>>) => ReactNode) | Falsy;
221
}
222

223
interface TransitionComponentProps<Item, Props extends object = any> extends UseTransitionProps<Item, Props> {
224
  /** Items to transition */
225
  items: OneOrMore<Item>;
226
  /** Render prop function for transition states */
227
  children: TransitionFn<Item, PickAnimated<Props>>;
228
}
229
```
230

231
### Utilities
232

233
Utility functions for advanced animation control, easing, and React integration.
234

235
```typescript { .api }
236
/**
237
 * Map the value of one or more dependencies using interpolation
238
 * @param source - Source values to interpolate
239
 * @param args - Interpolation configuration or function
240
 * @returns Interpolation instance
241
 */
242
const to: Interpolator;
243

244
/**
245
 * @deprecated Use the `to` export instead
246
 * Map the value of one or more dependencies using interpolation
247
 * @param source - Source values to interpolate
248
 * @param args - Interpolation configuration or function
249
 * @returns Interpolation instance
250
 */
251
const interpolate: Interpolator;
252

253
interface Interpolator {
254
  // Tuple of parent values
255
  <Input extends ReadonlyArray<any>, Output>(
256
    parents: Input,
257
    interpolator: (...args: Interpolated<Input>) => Output
258
  ): Interpolation<Output>;
259

260
  // Single parent value
261
  <Input, Output>(
262
    parent: FluidValue<Input> | Input,
263
    interpolator: InterpolatorFn<Input, Output>
264
  ): Interpolation<Output>;
265

266
  // Interpolation config
267
  <Out>(
268
    parents: OneOrMore<FluidValue>,
269
    config: InterpolatorConfig<Out>
270
  ): Interpolation<Animatable<Out>>;
271

272
  // Range shortcuts
273
  <Out>(
274
    parents: OneOrMore<FluidValue<number>> | FluidValue<number[]>,
275
    range: readonly number[],
276
    output: readonly Constrain<Out, Animatable>[],
277
    extrapolate?: ExtrapolateType
278
  ): Interpolation<Animatable<Out>>;
279
}
280

281
/**
282
 * Create custom interpolation functions
283
 * @param args - Interpolation configuration
284
 * @returns Interpolation function
285
 */
286
function createInterpolator<Input, Output>(
287
  args: InterpolatorArgs<Input, Output>
288
): (input: Input) => Output;
289

290
/**
291
 * SSR-safe useLayoutEffect hook
292
 * Same as useLayoutEffect in browser, useEffect on server
293
 */
294
const useIsomorphicLayoutEffect: typeof useLayoutEffect;
295

296
/**
297
 * Hook to respect user's motion preferences
298
 * @returns True if user prefers reduced motion
299
 */
300
function useReducedMotion(): boolean;
301

302
/**
303
 * Collection of easing functions for animations
304
 */
305
const easings: {
306
  linear: (t: number) => number;
307
  easeInQuad: (t: number) => number;
308
  easeOutQuad: (t: number) => number;
309
  easeInOutQuad: (t: number) => number;
310
  easeInCubic: (t: number) => number;
311
  easeOutCubic: (t: number) => number;
312
  easeInOutCubic: (t: number) => number;
313
  easeInQuart: (t: number) => number;
314
  easeOutQuart: (t: number) => number;
315
  easeInOutQuart: (t: number) => number;
316
  easeInQuint: (t: number) => number;
317
  easeOutQuint: (t: number) => number;
318
  easeInOutQuint: (t: number) => number;
319
  easeInSine: (t: number) => number;
320
  easeOutSine: (t: number) => number;
321
  easeInOutSine: (t: number) => number;
322
  easeInExpo: (t: number) => number;
323
  easeOutExpo: (t: number) => number;
324
  easeInOutExpo: (t: number) => number;
325
  easeInCirc: (t: number) => number;
326
  easeOutCirc: (t: number) => number;
327
  easeInOutCirc: (t: number) => number;
328
  easeInBack: (t: number) => number;
329
  easeOutBack: (t: number) => number;
330
  easeInOutBack: (t: number) => number;
331
  easeInElastic: (t: number) => number;
332
  easeOutElastic: (t: number) => number;
333
  easeInOutElastic: (t: number) => number;
334
  easeInBounce: (t: number) => number;
335
  easeOutBounce: (t: number) => number;
336
  easeInOutBounce: (t: number) => number;
337
};
338

339
/**
340
 * Infer animation target values from configuration
341
 * @param props - Animation configuration
342
 * @returns Inferred target values
343
 */
344
function inferTo(props: any): any;
345

346
/**
347
 * Predefined spring configurations for common animation styles
348
 */
349
const config: {
350
  default: { tension: 170; friction: 26 };
351
  gentle: { tension: 120; friction: 14 };
352
  wobbly: { tension: 180; friction: 12 };
353
  stiff: { tension: 210; friction: 20 };
354
  slow: { tension: 280; friction: 60 };
355
  molasses: { tension: 280; friction: 120 };
356
};
357

358
/**
359
 * Global configuration and frame loop controls
360
 */
361
const Globals: {
362
  assign(props: Partial<GlobalsProps>): void;
363
  skipAnimation: boolean;
364
  to: (source: any, args: any) => Interpolation;
365
};
366

367
/**
368
 * Advance all animations by the given time
369
 * @param dt - Delta time in milliseconds
370
 */
371
const update: (dt?: number) => void;
372
```
373

374
## Common Types
375

376
```typescript { .api }
377
type Length = number | string;
378
type Angle = number | string;
379

380
type AnimatedProps<Props extends object> = {
381
  [P in keyof Props]: P extends 'ref' | 'key'
382
    ? Props[P]
383
    : AnimatedProp<Props[P]>;
384
};
385

386
type UseSpringProps<Props extends object = any> = ControllerUpdate<
387
  PickAnimated<Props>
388
> & {
389
  ref?: SpringRef<PickAnimated<Props>>;
390
};
391

392
interface SpringValues<State extends Lookup> {
393
  [key: string]: SpringValue;
394
}
395

396
type TransitionFn<Item, State extends Lookup> = (
397
  style: SpringValues<State>,
398
  item: Item,
399
  transition: TransitionState<Item>,
400
  index: number
401
) => React.ReactElement;
402
```