Composables
useParallax
requestAnimationFrame parallax effect for .xParallax[data-parallax-speed] elements.
useParallax
Attaches a requestAnimationFrame scroll listener that applies a CSS translateY transform to every .xParallax[data-parallax-speed] element in the document. The speed multiplier is read from each element's data-parallax-speed attribute (e.g. 0.3 = 30% of scroll position). Called automatically by the marketing.client.ts plugin — use directly for fine-grained control.
The composable registers lifecycle hooks automatically, so it must be called inside a component setup. Calling it outside a component instance returns a no-op stub.
Usage
// Called automatically by the global plugin on mount.
// Call directly when you need manual control:
useParallax()
// With custom options:
useParallax({ defaultSpeed: 0.5 })
Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
options | object | {} | Parallax tuning options. |
options.defaultSpeed | number | 0.5 | Fallback speed multiplier when an element does not define data-parallax-speed. Lower values = subtler effect. |
Returns
| Key | Type | Description |
|---|---|---|
initParallax | () => void | Manually start the parallax listener (queries DOM, attaches scroll handler, runs initial update). The plugin calls this for you on mount. |
cleanup | () => void | Remove the scroll listener and clear the elements ref. Called automatically on unmount. |
Behavior
| Effect | Description |
|---|---|
Watches .xParallax[data-parallax-speed] | All matching elements get a translateY applied on scroll. |
Reads data-parallax-speed | Per-element speed multiplier (e.g. 0.3 = 30% of scroll position). |
| RAF loop | Uses requestAnimationFrame for smooth, jank-free animation. |
| Cleanup | The scroll listener is removed automatically when the component unmounts. |
Example
<script setup>
// Re-initialize after dynamically adding parallax elements
useParallax({ defaultSpeed: 0.4 })
</script>
<template>
<div class="xParallax" data-parallax-speed="0.3">
<img src="/hero-bg.jpg" alt="Background" />
</div>
</template>
AI Context
composable: useParallax
package: "@xenterprises/nuxt-x-marketing"
use-when: >
Applying scroll-driven depth effects to background images or decorative
elements. The plugin initializes this automatically — only call directly
for re-initialization or a custom defaultSpeed. For single-element
parallax controlled via a template ref, use useElementParallax instead.
Requires .xParallax class and data-parallax-speed attribute on target
elements.