Appearance
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.
| Value | Effect |
|---|---|
translate (default) | 2D translation — classic parallax. |
rotate | Rotation in degrees. |
scale | Uniform scale (both axes). |
scaleX | Horizontal-only scale. |
scaleY | Vertical-only scale. |
depth | Z-translation in 3D space (requires the host's perspective). |
depth_inv | Inverse Z-translation — pushes layers backward. |
custom | The 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
| Slot | Slot props | Description |
|---|---|---|
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 variable | Value |
|---|---|
--origam-parallax__element---x | horizontal movement amount |
--origam-parallax__element---y | vertical 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
transformstyles 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.
Related
OrigamParallax— the host that emits the movement context this element consumes.