Skip to content

OrigamParallaxElement ​

<OrigamParallaxElement> is the layer primitive that consumes the movement vector emitted by an enclosing <OrigamParallax> and applies it as a CSS transform on its host element. Each element picks its own transform type (translate / rotate / scale / depth) and strength, so a single parallax host can compose foreground, midground and background layers with different feels.

The element must be nested inside an <OrigamParallax> — it throws on mount otherwise (the movement context is inject-ed via ORIGAM_PARALLAX_KEY).

Basic usage ​

vue
<template>
    <OrigamParallax>
        <OrigamParallaxElement :strength="20" type="translate">
            <img src="/img/cover.jpg" alt="" />
        </OrigamParallaxElement>
    </OrigamParallax>
</template>

Transform type ​

type selects which CSS transform the element applies. Values come from the PARALLAX_ELEMENT_TYPE enum.

ValueEffect
translate (default)2D translation — classic parallax.
rotateRotation in degrees.
scaleUniform scale (both axes).
scaleXHorizontal-only scale.
scaleYVertical-only scale.
depthZ-translation in 3D space (requires the host's perspective).
depth_invInverse Z-translation — pushes layers backward.
customThe component writes no transform and instead publishes the movement as two CSS variables — you write the transform. See Writing your own transform.
vue
<template>
    <OrigamParallax>
        <OrigamParallaxElement type="translate" :strength="30">…</OrigamParallaxElement>
        <OrigamParallaxElement type="rotate"    :strength="6">…</OrigamParallaxElement>
        <OrigamParallaxElement type="scale"     :strength="0.05">…</OrigamParallaxElement>
        <OrigamParallaxElement type="depth"     :strength="60">…</OrigamParallaxElement>
    </OrigamParallax>
</template>

Strength & axis ​

strength is the multiplier applied to the normalised movement vector (higher = more dramatic). axis constrains the movement to a single axis (x or y); leave it unset for full 2D motion.

vue
<template>
    <OrigamParallaxElement :strength="40" axis="y">…</OrigamParallaxElement>
</template>

Origin ​

transformOrigin accepts any CSS transform-origin value (default 'center'). originX / originY (0–100, percent) parametrise the elementMovement utility — the layer reacts more strongly the further the cursor moves from this point.

vue
<template>
    <OrigamParallaxElement
        transform-origin="top left"
        :origin-x="0"
        :origin-y="0"
        :strength="20"
    >…</OrigamParallaxElement>
</template>

Clamping (min / max) ​

Cap the movement on either axis to keep the layer inside its frame.

vue
<template>
    <OrigamParallaxElement
        :min-x="-20"
        :max-x="20"
        :min-y="-10"
        :max-y="10"
        :strength="30"
    >…</OrigamParallaxElement>
</template>

Cyclic mode ​

Set cycle > 0 to switch from "follow the cursor" to a sinusoidal oscillation (number of cycles per pass). Useful for ambient backgrounds.

vue
<template>
    <OrigamParallaxElement :cycle="2" :strength="20">…</OrigamParallaxElement>
</template>

Audio mode ​

When the host streams audio data, audioIndex (0–100+) selects the FFT bucket the element listens to. Mouse / scroll movement is ignored while audio data is being read.

vue
<template>
    <OrigamParallax audio="/sound/loop.mp3">
        <OrigamParallaxElement :audio-index="32" type="scale" :strength="0.4">…</OrigamParallaxElement>
    </OrigamParallax>
</template>

Polymorphic tag ​

vue
<template>
    <OrigamParallaxElement tag="figure">…</OrigamParallaxElement>
</template>

Slots ​

SlotSlot propsDescription
default—The actual layer content (image, text, …).

Props (interface) ​

ts
interface IParallaxElementProps extends ICommonsComponentProps,
    ITagProps, IPaddingProps, IMarginProps, IBorderProps,
    IRoundedProps, IElevationProps, IParallaxElementTypeProps {
    type?: TParallaxElementType  // default 'translate'
    transformOrigin?: TAnchor    // default 'center'
    originX?: number             // default 50
    originY?: number             // default 50
    strength?: number            // default 10
    axis?: TAxis                 // 'x' | 'y' (unset = both)
    minX?: number
    maxX?: number
    minY?: number
    maxY?: number
    cycle?: number               // default 0 (linear). >0 switches to cyclic mode
    audioIndex?: number          // default 50
}

Writing your own transform (type="custom") ​

The seven built-in types each compose a fixed transform. custom composes none: it publishes the computed movement and hands the decision to you.

CSS variableValue
--origam-parallax__element---xhorizontal movement amount
--origam-parallax__element---yvertical movement amount

Both are plain numbers with no unit, and that is deliberate: the same figure means pixels for a translation, degrees for a rotation and a ratio for a scale. Pinning px here would have closed the hatch to the other two. You multiply by whatever unit your transform needs:

vue
<origam-parallax>
    <origam-parallax-element
            :strength="40"
            type="custom"
            :style="{
                transform: 'rotate3d(0, 0, 1, calc(var(--origam-parallax__element---x) * 1deg))'
            }"
    >
        Tilts with the pointer
    </origam-parallax-element>
</origam-parallax>

A stylesheet rule works just as well as the inline :style above — the two variables live on the element itself, so any selector that reaches it can read them.

The values already have strength applied (along with axis, min*, max* and cycle), so every other prop keeps working under custom; you only choose the transform function, never the movement maths.

transition-property: transform is still set by the component, so a CSS-authored transform animates exactly like the built-in types.

No CSS, no movement

custom renders no transform on its own. If you select it and write no rule, the element sits still — that is the contract, not a bug. Until v2.16 this type silently did nothing at all and there was no way to make it do anything; the variables are what makes the promise real.

Anatomy ​

html
<div class="origam-parallax-element" style="transform: …; transition: …;">
    <!-- default slot -->
</div>

Design tokens consumed ​

<OrigamParallaxElement> shares the --origam-parallax---* / --origam-parallax__element---* variables declared in packages/ds/src/assets/css/tokens/light.css and dark.css with its host.

The full list lives in packages/ds/src/assets/css/tokens/light.css and dark.css — grep for --origam-parallax.

Transition duration is a prop, not a token ​

Transition duration and easing are applied inline by the component, sourced from the parent <OrigamParallax>'s duration / easing props so that every element in a host stays in sync. Set them on the parent:

vue
<origam-parallax :duration="450">
    <origam-parallax-element :strength="30" type="translate">…</origam-parallax-element>
</origam-parallax>

A token used to be documented here, and it never worked

This page previously listed --origam-parallax__element---transition-duration in a "Design tokens consumed" table. It was declared in the token stylesheets but read by nothing, and it could not have worked even if it had been: the component writes transition-duration as an inline style, which outranks any stylesheet declaration. The token has been removed from light.css, dark.css, their SCSS twins and tokens.type.ts.

Wiring it as var(--token, <prop value>) was considered and rejected — it would let a theme override an explicitly passed prop, inverting the props-first rule the design system is built on.

easing="spring" resolves through --origam-parallax---transition-easing-spring ​

Unlike duration above, easing is a closed enum ('linear' | 'ease-out' | 'spring'), not a literal value the caller fully specifies — 'linear' and 'ease-out' already ARE valid CSS transition-timing-function keywords and are forwarded as-is, but 'spring' is not a CSS keyword at all. The browser silently drops an invalid transition-timing-function: spring declaration (no error, no visible effect), so this legacy mouse/scroll path previously ignored easing="spring" entirely. The concrete curve a theme wants "spring" to look like — not a value the easing prop itself carries — comes from var(--origam-parallax---transition-easing-spring, cubic-bezier(0.16, 1, 0.3, 1)), the same layering variant="primary" already uses for its colour (the prop picks the category, the token defines the category). This does not reintroduce the rejected pattern above: nothing here lets a theme override the caller's CHOICE of easing, only what 'spring' concretely renders as once chosen.

Accessibility ​

  • Layers driven by parallax should never carry essential information — the effect is purely decorative. Pair with a static fallback composition for prefers-reduced-motion.
  • Inline transform styles can interact with screen-magnifier trackers. Keep movement amplitudes (strength) reasonable on text-bearing layers.

Theming notes ​

  • The element ships no color tokens. Style its inner content (image, div, …) with the standard origam tokens (--origam-color-*) for theme awareness.
  • OrigamParallax — the host that emits the movement context this element consumes.