Skip to content

OrigamParallax ​

<OrigamParallax> is the host that drives a parallax effect across one or more <OrigamParallaxLayer> (or legacy <OrigamParallaxElement>) children. It tracks scroll progress, mouse-ratio (for the 2D mode) and device orientation; the layers register themselves against the host and their transform is mutated outside Vue reactivity for performance.

CSS-first: when the browser supports animation-timeline: scroll() (Chrome 115+, Edge 115+, Safari TP) AND easing="linear", the runtime delegates the per-frame work to the CSS scroll-driven animation. On older browsers, or when easing is ease-out / spring, a requestAnimationFrame fallback takes over. prefers-reduced-motion: reduce keeps every layer at its static offsetX / offsetY regardless of scroll.

Quick start — single layer (legacy API, backward-compatible) ​

vue
<template>
    <OrigamParallax style="height: 320px; width: 100%;">
        <OrigamParallaxElement :strength="20">
            <img src="/img/cover.jpg" alt="" />
        </OrigamParallaxElement>
    </OrigamParallax>
</template>

Quick start — multi-layer (enriched) ​

vue
<template>
    <OrigamParallax direction="vertical" easing="spring">
        <OrigamParallaxLayer :speed="0.2">
            <img src="/bg.jpg" alt="" />
        </OrigamParallaxLayer>
        <OrigamParallaxLayer :speed="0.5">
            <img src="/midground.png" alt="" />
        </OrigamParallaxLayer>
        <OrigamParallaxLayer :speed="0.8">
            <img src="/foreground.png" alt="" />
        </OrigamParallaxLayer>
    </OrigamParallax>
</template>

<OrigamParallaxLayer> (new) and <OrigamParallaxElement> (legacy) live in two independent injection contexts. Both can coexist inside the same <OrigamParallax>.

Props (table) ​

PropTypeDefaultDescription
direction'vertical' | 'horizontal' | 'both''vertical'Axis of the parallax translation. both mixes scroll-progress (Y) and mouse-ratio (X).
easing'linear' | 'ease-out' | 'spring' | string'linear'Easing keyword or raw CSS timing-function. Only linear activates the CSS-first path.
speednumber0.5Default speed multiplier when the host has no <OrigamParallaxLayer> children.
disabledbooleanfalseHard kill-switch. <OrigamParallaxLayer> and <OrigamParallaxElement> stay at offset 0 regardless of the event source — scroll, mouse, or device orientation. See "disabled vs active" below.
thresholdnumber0Proportion of the host (0 → 1) that must enter the viewport before the effect activates.
durationnumber1000Legacy transition duration (ms) for <OrigamParallaxElement>.
perspectivenumber1000Host CSS perspective (px).
event'move' | 'scroll' | 'orientation''move'Legacy event source for <OrigamParallaxElement>.
activebooleantrueNarrow legacy kill-switch — freezes the mouse path only. See "disabled vs active" below.
animationDurationnumberundefinedDeprecated — alias for duration, removed in v3.0.0.

Plus all the standard chrome props: tag, color, bgColor, padding, margin, border, rounded, elevation, dimension, audio, class, style.

disabled vs active ​

Both stop the effect, and the difference is deliberate — they are not synonyms.

disabledactive={false}
ScopeEvery path: <OrigamParallaxLayer> runtime and the legacy <OrigamParallaxElement>Legacy <OrigamParallaxElement> only
Event sources stoppedscroll, move, orientationmove only — event="scroll" keeps running
Resting positionSnaps back to offset 0, including mid-gestureStops where it is
Intended useSSR, snapshot tests, prefers-reduced-motion integrationsLegacy v2.x pause of the mouse effect

Reach for disabled unless you specifically want the narrow, legacy behaviour. Until v2.15.x, disabled was silently inert on the legacy <OrigamParallaxElement> mouse path — a host with <origam-parallax disabled event="move"> kept translating under the cursor.

Events ​

EventPayloadFires
enter—The host enters the viewport (IntersectionObserver).
leave—The host leaves the viewport.
scroll-progressprogress: number (0 → 1)On every rAF tick while the host is visible. 0 = just entered, 1 = just left.
vue
<template>
    <OrigamParallax
        @enter="onEnter"
        @leave="onLeave"
        @scroll-progress="onProgress"
    >…</OrigamParallax>
</template>

IParallaxLayerProps ​

ts
interface IParallaxLayerProps {
    speed?: number     // 0 = fixed, 0.5 = half speed, 1 = neutral, >1 = faster, <0 = reversed
    offsetX?: number   // static X offset (px) on top of the parallax translation
    offsetY?: number   // static Y offset (px)
    zIndex?: number    // optional stacking override
}

CSS-first vs JS fallback ​

ConditionPath
CSS.supports('animation-timeline: scroll()') is true AND easing === 'linear'CSS — animation-timeline: view() keyframe animation on each layer. Zero JS work per frame.
Either condition above is falseJS fallback — IntersectionObserver + requestAnimationFrame mutate transform directly. Spring easing uses a damped lerp.

The runtime exposes the active path via cssScrollDriven (a reactive ref on the component instance) — useful for storybook diagnostics or custom debug overlays. The branch is computed at mount and re-evaluated when the easing prop changes.

prefers-reduced-motion behavior ​

When (prefers-reduced-motion: reduce) matches, every layer:

  • Snaps to translate3d(offsetX, offsetY, 0) and never moves.
  • The CSS keyframe animation is disabled via animation: none !important.
  • The rAF loop short-circuits before mutating the DOM.

The runtime watches the media-query and reacts live to OS-level changes without a page reload.

Performance tips ​

  • Layers carry will-change: transform via the --origam-parallax__layer---will-change token. Avoid stacking too many layers (>5) on a single host — every one is a promoted compositing layer in the GPU.
  • The runtime mutates transform directly (not via a Vue render), so a parallax page should not trigger any extra component re-renders on scroll.
  • Prefer easing="linear" when targeting recent Chromium — the CSS-first path is the cheapest by an order of magnitude.

Anatomy ​

html
<div class="origam-parallax origam-parallax--vertical">
    <!-- <OrigamParallaxLayer> children -->
    <div class="origam-parallax__layer" style="transform: translate3d(…)"></div>
    <!-- <OrigamParallaxElement> legacy children -->
    <div class="origam-parallax-element" style="transform: …"></div>
    <audio v-if="audio" />
</div>

Design tokens consumed ​

<OrigamParallax> reads its variables from packages/ds/src/assets/css/tokens/light.css and dark.css (SCSS twins under packages/ds/src/assets/scss/tokens/). The relevant additions for the multi-layer path are:

CSS variableToken
--origam-parallax---transition-duration-spring{motion.duration.xslow}
--origam-parallax---transition-easing-default{motion.easing.standard}
--origam-parallax---transition-easing-springcubic-bezier(0.16, 1, 0.3, 1)
--origam-parallax__layer---will-changetransform
--origam-parallax__layer---transform-origincenter center

Accessibility ​

  • Layers are decorative; no ARIA attributes are needed on the parallax host. Content (text, images) inside the slots remains lisible by screen readers — the runtime only modifies transform.
  • prefers-reduced-motion is honoured by default; consumers do NOT need to bind anything to disabled.
  • The legacy event="orientation" mode requires explicit user permission on iOS (DeviceOrientationEvent.requestPermission()) — gate it behind a user gesture.
  • Audio reactivity (audio prop) starts only after a user gesture in most browsers.
  • OrigamParallaxLayer — new layer primitive consumed by the multi-layer runtime.
  • OrigamParallaxElement — legacy primitive for mouse-driven / audio-reactive effects (type="rotate", type="depth", …).