useParallaxRuntime

Parallax
stable

Headless parallax engine used by OrigamParallax. Maintains a registry of layers, tracks scroll progress via IntersectionObserver, and drives per-frame transforms via requestAnimationFrame. Branches automatically to a CSS scroll-driven animation path (Chrome 115+) when the easing is linear and the browser supports animation-timeline: scroll(). Respects prefers-reduced-motion at OS level.

API

Signature

Full TypeScript signature sourced from the composable file.

typescript

Consumed interfaces

IParallaxLayerRegistry

API

Parameters

Input parameters accepted by this composable.

options
required
IUseParallaxRuntimeOptions
options.target
required
Ref<HTMLElement | undefined>
Template ref of the parallax host element. The IntersectionObserver and scroll listener are attached to this element.
options.direction
required
Ref<TParallaxDirection>
Axis of movement: "vertical" (default), "horizontal", or "both" (scroll on Y + mouse on X).
options.easing
required
Ref<TParallaxEasing | string>
Easing mode: "linear" (enables CSS scroll-driven path), "spring" (JS lerp with damping), or a CSS easing string.
options.threshold
required
Ref<number>
Minimum viewport intersection ratio [0-1] before progress starts. Delays animation until the host is sufficiently visible.
options.disabled
required
Ref<boolean>
When true, layers are snapped to their static offsets and the rAF loop is paused.
options.speed
required
Ref<number>
Default speed factor for raw content (non-layer slot). Layer registrations carry their own speed override.
options.onEnter
() => void
Callback fired when the host enters the viewport.
options.onLeave
() => void
Callback fired when the host exits the viewport.
options.onProgress
(progress: number) => void
Called on every scroll frame with the current normalised progress value in [0, 1].

API

Return values

Properties and methods exposed by the composable return object.

layers
Live list of registered layer descriptors. Each entry carries its target element, speed, and static offsets.
progress
Normalised scroll progress in [0, 1]. 0 = host top at viewport bottom, 1 = host bottom at viewport top.
mouseRatio
Mouse position ratio in [-1, 1] for each axis from the host centre. Only updated when direction is "both".
cssScrollDriven
True when the CSS scroll-driven animation path is active (animation-timeline: scroll() supported + easing === "linear").
reducedMotion
Reflects the prefers-reduced-motion media query. When true, all layers are locked to their static offsets.
register
Registers a layer provided by an OrigamParallaxLayer child. Called automatically via provide/inject on mount.
unregister
Removes a layer by its unique symbol ID. Called on layer unmount.

Usage

Examples

Ready-to-paste usage snippets.

Vertical parallax with multiple layers

vue

Mouse-driven parallax (direction both)

vue