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
Signature TypeScript complète extraite du fichier du composable.
Interfaces consommées
IParallaxLayerRegistry
API
Paramètres
Paramètres d'entrée acceptés par ce composable.
- optionsrequisIUseParallaxRuntimeOptions
- options.targetrequisRef<HTMLElement | undefined>
- Template ref of the parallax host element. The IntersectionObserver and scroll listener are attached to this element.
- options.directionrequisRef<TParallaxDirection>
- Axis of movement: "vertical" (default), "horizontal", or "both" (scroll on Y + mouse on X).
- options.easingrequisRef<TParallaxEasing | string>
- Easing mode: "linear" (enables CSS scroll-driven path), "spring" (JS lerp with damping), or a CSS easing string.
- options.thresholdrequisRef<number>
- Minimum viewport intersection ratio [0-1] before progress starts. Delays animation until the host is sufficiently visible.
- options.disabledrequisRef<boolean>
- When true, layers are snapped to their static offsets and the rAF loop is paused.
- options.speedrequisRef<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
Valeurs de retour
Propriétés et méthodes exposées par l'objet retourné par le composable.
- 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
Exemples
Extraits de code prêts à coller.
Vertical parallax with multiple layers
Mouse-driven parallax (direction both)