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.
Consumed interfaces
IParallaxLayerRegistry
API
Parameters
Input parameters accepted by this composable.
- optionsrequiredIUseParallaxRuntimeOptions
- options.targetrequiredRef<HTMLElement | undefined>
- Template ref of the parallax host element. The IntersectionObserver and scroll listener are attached to this element.
- options.directionrequiredRef<TParallaxDirection>
- Axis of movement: "vertical" (default), "horizontal", or "both" (scroll on Y + mouse on X).
- options.easingrequiredRef<TParallaxEasing | string>
- Easing mode: "linear" (enables CSS scroll-driven path), "spring" (JS lerp with damping), or a CSS easing string.
- options.thresholdrequiredRef<number>
- Minimum viewport intersection ratio [0-1] before progress starts. Delays animation until the host is sufficiently visible.
- options.disabledrequiredRef<boolean>
- When true, layers are snapped to their static offsets and the rAF loop is paused.
- options.speedrequiredRef<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
Mouse-driven parallax (direction both)