0
# Animation & Effects
1

2
Animation utilities, scroll management, and visual effects for creating engaging user interfaces with smooth transitions and responsive interactions.
3

4
## Capabilities
5

6
### Scroll Management
7

8
#### useScroll
9

10
Reactive scroll position tracking with arrival state detection.
11

12
```typescript { .api }
13
/**
14
 * Reactive scroll position with arrival state detection
15
 * @param element - Target element or ref
16
 * @param options - Configuration options
17
 * @returns Scroll state and utilities
18
 */
19
function useScroll(
20
  element: MaybeComputedElementRef,
21
  options?: UseScrollOptions
22
): UseScrollReturn;
23

24
interface UseScrollReturn {
25
  x: Ref<number>;
26
  y: Ref<number>;
27
  isScrolling: Ref<boolean>;
28
  arrivedState: ScrollState;
29
  directions: ScrollDirections;
30
  measure(): void;
31
}
32

33
interface ScrollState {
34
  left: boolean;
35
  right: boolean;
36
  top: boolean;
37
  bottom: boolean;
38
}
39

40
interface ScrollDirections {
41
  left: boolean;
42
  right: boolean;
43
  top: boolean;
44
  bottom: boolean;
45
}
46

47
interface UseScrollOptions {
48
  throttle?: number;
49
  idle?: number;
50
  onScroll?: (e: Event) => void;
51
  onStop?: (e: Event) => void;
52
  eventListenerOptions?: boolean | AddEventListenerOptions;
53
  behavior?: MaybeRefOrGetter<ScrollBehavior>;
54
  window?: Window;
55
}
56
```
57

58
**Usage Examples:**
59

60
```typescript
61
import { ref } from "vue";
62
import { useScroll } from "@vueuse/core";
63

64
const el = ref<HTMLElement>();
65
const { x, y, isScrolling, arrivedState, directions } = useScroll(el);
66

67
// Check if scrolled to edges
68
console.log(arrivedState.top); // true when at top
69
console.log(arrivedState.bottom); // true when at bottom
70

71
// Check scroll direction
72
console.log(directions.top); // true when scrolling up
73
console.log(directions.left); // true when scrolling left
74
```
75

76
#### useWindowScroll
77

78
Reactive window scroll position tracking.
79

80
```typescript { .api }
81
/**
82
 * Reactive window scroll position
83
 * @param options - Configuration options
84
 * @returns Window scroll state
85
 */
86
function useWindowScroll(options?: UseScrollOptions): UseScrollReturn;
87
```
88

89
#### useScrollLock
90

91
Lock scrolling of body or specific elements.
92

93
```typescript { .api }
94
/**
95
 * Lock scrolling of an element
96
 * @param element - Target element or ref (defaults to body)
97
 * @param initialState - Initial lock state
98
 * @returns Scroll lock utilities
99
 */
100
function useScrollLock(
101
  element?: MaybeElementRef,
102
  initialState?: boolean
103
): WritableComputedRef<boolean>;
104
```
105

106
#### useInfiniteScroll
107

108
Infinite scroll functionality with automatic loading.
109

110
```typescript { .api }
111
/**
112
 * Infinite scroll functionality
113
 * @param element - Scrollable element or ref
114
 * @param onLoadMore - Load more callback
115
 * @param options - Configuration options
116
 * @returns Infinite scroll state
117
 */
118
function useInfiniteScroll(
119
  element: MaybeElementRef,
120
  onLoadMore: (state: UseInfiniteScrollReturn) => Awaitable<void>,
121
  options?: UseInfiniteScrollOptions
122
): UseInfiniteScrollReturn;
123

124
interface UseInfiniteScrollReturn {
125
  isLoading: Ref<boolean>;
126
  isFinished: WritableComputedRef<boolean>;
127
  pause: () => void;
128
  resume: () => void;
129
  reset: () => void;
130
}
131

132
interface UseInfiniteScrollOptions {
133
  distance?: number;
134
  direction?: 'top' | 'bottom' | 'left' | 'right';
135
  preserveScrollPosition?: boolean;
136
  throttle?: number;
137
  idle?: number;
138
  canLoadMore?: (el: Element) => boolean;
139
}
140
```
141

142
### Animations
143

144
#### useAnimate
145

146
Reactive Web Animations API wrapper.
147

148
```typescript { .api }
149
/**
150
 * Reactive Web Animations API wrapper
151
 * @param target - Target element or ref
152
 * @param keyframes - Animation keyframes
153
 * @param options - Animation options
154
 * @returns Animation utilities
155
 */
156
function useAnimate(
157
  target: MaybeElementRef,
158
  keyframes: MaybeRefOrGetter<Keyframe[]>,
159
  options?: MaybeRefOrGetter<number | KeyframeAnimationOptions>
160
): UseAnimateReturn;
161

162
interface UseAnimateReturn {
163
  isSupported: Ref<boolean>;
164
  animate: Ref<Animation | undefined>;
165
  play: () => void;
166
  pause: () => void;
167
  reverse: () => void;
168
  finish: () => void;
169
  cancel: () => void;
170
  pending: Ref<boolean>;
171
  playState: Ref<AnimationPlayState>;
172
  replaceState: Ref<AnimationReplaceState>;
173
  startTime: Ref<CSSNumberish | null>;
174
  currentTime: Ref<CSSNumberish | null>;
175
  timeline: Ref<AnimationTimeline | null>;
176
  playbackRate: Ref<number>;
177
}
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
import { ref } from "vue";
184
import { useAnimate } from "@vueuse/core";
185

186
const el = ref<HTMLElement>();
187

188
// Simple fade animation
189
const { play, pause, reverse } = useAnimate(
190
  el,
191
  [
192
    { opacity: 0 },
193
    { opacity: 1 }
194
  ],
195
  {
196
    duration: 1000,
197
    easing: 'ease-in-out'
198
  }
199
);
200

201
// Complex keyframe animation
202
const { play } = useAnimate(
203
  el,
204
  [
205
    { transform: 'translateX(0px)', opacity: 1 },
206
    { transform: 'translateX(100px)', opacity: 0.5 },
207
    { transform: 'translateX(200px)', opacity: 1 }
208
  ],
209
  {
210
    duration: 2000,
211
    iterations: Infinity,
212
    direction: 'alternate'
213
  }
214
);
215
```
216

217
#### useTransition
218

219
Create smooth transitions between values.
220

221
```typescript { .api }
222
/**
223
 * Create smooth transitions between values
224
 * @param source - Source value to transition
225
 * @param options - Transition options
226
 * @returns Transitioning value
227
 */
228
function useTransition(
229
  source: Ref<number>,
230
  options?: UseTransitionOptions
231
): Ref<number>;
232

233
function useTransition<T extends MaybeRefOrGetter<number>[]>(
234
  source: [...T],
235
  options?: UseTransitionOptions
236
): ComputedRef<{ [K in keyof T]: number }>;
237

238
interface UseTransitionOptions {
239
  delay?: MaybeRefOrGetter<number>;
240
  disabled?: MaybeRefOrGetter<boolean>;
241
  duration?: MaybeRefOrGetter<number>;
242
  onFinished?: () => void;
243
  onStarted?: () => void;
244
  transition?: TransitionPresets | CubicBezierPoints | EasingFunction;
245
}
246

247
type TransitionPresets = 'linear' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuint' | 'easeOutQuint' | 'easeInOutQuint' | 'easeInCirc' | 'easeOutCirc' | 'easeInOutCirc' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack';
248
```
249

250
### CSS Effects
251

252
#### useCssVar
253

254
Reactive CSS custom properties (CSS variables).
255

256
```typescript { .api }
257
/**
258
 * Reactive CSS custom properties
259
 * @param prop - CSS property name (with or without --)
260
 * @param target - Target element or ref
261
 * @param options - Configuration options
262
 * @returns Reactive CSS variable ref
263
 */
264
function useCssVar(
265
  prop: MaybeRefOrGetter<string>,
266
  target?: MaybeElementRef,
267
  options?: UseCssVarOptions
268
): WritableComputedRef<string>;
269

270
interface UseCssVarOptions extends ConfigurableWindow {
271
  initialValue?: string;
272
  observe?: boolean;
273
}
274
```
275

276
#### useStyleTag
277

278
Create and manage style tags dynamically.
279

280
```typescript { .api }
281
/**
282
 * Create and manage style tags dynamically
283
 * @param css - CSS content (reactive)
284
 * @param options - Configuration options
285
 * @returns Style tag utilities
286
 */
287
function useStyleTag(
288
  css: MaybeRefOrGetter<string>,
289
  options?: UseStyleTagOptions
290
): UseStyleTagReturn;
291

292
interface UseStyleTagReturn {
293
  id: string;
294
  css: Ref<string>;
295
  load: () => void;
296
  unload: () => void;
297
  isLoaded: Readonly<Ref<boolean>>;
298
}
299

300
interface UseStyleTagOptions extends ConfigurableDocument {
301
  immediate?: boolean;
302
  manual?: boolean;
303
  id?: string;
304
  media?: string;
305
}
306
```
307

308
#### useScriptTag
309

310
Load and manage script tags dynamically.
311

312
```typescript { .api }
313
/**
314
 * Load and manage script tags dynamically  
315
 * @param src - Script source URL (reactive)
316
 * @param onLoaded - Callback when script loads
317
 * @param options - Configuration options
318
 * @returns Script tag utilities
319
 */
320
function useScriptTag(
321
  src: MaybeRefOrGetter<string>,
322
  onLoaded?: (el: HTMLScriptElement) => void,
323
  options?: UseScriptTagOptions
324
): UseScriptTagReturn;
325

326
interface UseScriptTagReturn {
327
  scriptTag: Ref<HTMLScriptElement | null>;
328
  load: (waitForScriptLoad?: boolean) => Promise<HTMLScriptElement | boolean>;
329
  unload: () => void;
330
}
331

332
interface UseScriptTagOptions extends ConfigurableDocument {
333
  immediate?: boolean;
334
  async?: boolean;
335
  type?: string;
336
  manual?: boolean;
337
  crossOrigin?: 'anonymous' | 'use-credentials';
338
  referrerPolicy?: ReferrerPolicy;
339
  noModule?: boolean;
340
  defer?: boolean;
341
  document?: Document;
342
  attrs?: Record<string, string>;
343
}
344
```
345

346
### Fullscreen Management
347

348
#### useFullscreen
349

350
Reactive Fullscreen API management.
351

352
```typescript { .api }
353
/**
354
 * Reactive Fullscreen API
355
 * @param target - Target element or ref
356
 * @param options - Configuration options
357
 * @returns Fullscreen utilities
358
 */
359
function useFullscreen(
360
  target?: MaybeElementRef,
361
  options?: UseFullscreenOptions
362
): UseFullscreenReturn;
363

364
interface UseFullscreenReturn {
365
  isSupported: ComputedRef<boolean>;
366
  isFullscreen: Ref<boolean>;
367
  enter: () => Promise<void>;
368
  exit: () => Promise<void>;
369
  toggle: () => Promise<void>;
370
}
371

372
interface UseFullscreenOptions extends ConfigurableDocument {
373
  autoExit?: boolean;
374
}
375
```
376

377
### Performance & Animation Frame
378

379
#### useRafFn
380

381
Reactive requestAnimationFrame utility.
382

383
```typescript { .api }
384
/**
385
 * Reactive requestAnimationFrame utility
386
 * @param fn - Function to call on each frame
387
 * @param options - Configuration options
388
 * @returns Animation frame utilities
389
 */
390
function useRafFn(
391
  fn: (args: UseRafFnCallbackArguments) => void,
392
  options?: UseRafFnOptions
393
): Pausable;
394

395
interface UseRafFnCallbackArguments {
396
  delta: number;
397
  timestamp: DOMHighResTimeStamp;
398
}
399

400
interface UseRafFnOptions {
401
  immediate?: boolean;
402
  fpsLimit?: number;
403
}
404
```
405

406
#### useFps
407

408
Reactive FPS (frames per second) counter.
409

410
```typescript { .api }
411
/**
412
 * Reactive FPS counter
413
 * @param options - Configuration options
414
 * @returns FPS state
415
 */
416
function useFps(options?: UseFpsOptions): Ref<number>;
417

418
interface UseFpsOptions {
419
  every?: number;
420
}
421
```
422

423
### Parallax Effects
424

425
#### useParallax
426

427
Create parallax effects based on mouse movement or device orientation.
428

429
```typescript { .api }
430
/**
431
 * Create parallax effects based on mouse movement
432
 * @param target - Target element or ref
433
 * @param options - Configuration options
434
 * @returns Parallax transform values
435
 */
436
function useParallax(
437
  target: MaybeElementRef,
438
  options?: UseParallaxOptions
439
): UseParallaxReturn;
440

441
interface UseParallaxReturn {
442
  tilt: ComputedRef<number>;
443
  roll: ComputedRef<number>;
444
  source: 'mouse' | 'deviceOrientation';
445
}
446

447
interface UseParallaxOptions {
448
  deviceOrientationTiltAdjust?: (i: number) => number;
449
  deviceOrientationRollAdjust?: (i: number) => number;
450
  mouseTiltAdjust?: (i: number) => number;
451
  mouseRollAdjust?: (i: number) => number;
452
}
453
```