StringParallax Module

Orchestrate layered depth by converting scroll offset into vertical translation. StringParallax extends the progress engine and pushes elements along the Y axis with transform updates scoped to the current frame.

Activation primer: Add string="parallax" to every element you want StringParallax to move. Supply string-id="your-id" when you need a stable handle for events, mirrors, or string-copy-from; otherwise StringTune generates one automatically.

HTML Attributes

Attribute	Type	Default	Controls	Practical notes
`string-parallax`	number	`0.2`	Movement strength expressed as a multiplier of viewport height	Positive values move opposite the scroll direction; use negatives for inverted depth
`string-parallax-bias`	number	`0.0`	Balance point between pre-scroll and post-scroll travel	Range `0`–`1`; shift toward `1` to emphasise exit motion
`string-offset-top`	dimension	auto (`strength * viewport`)	Additional distance before motion begins	Override when you need tighter envelopes than the auto scaling
`string-offset-bottom`	dimension	auto (`strength * viewport`)	Extra travel before motion completes	Match top offset for symmetric movement
`string-enter-el` / `string-enter-vp`	enum (`top`/`bottom`/`left`/`right`)	`top` / `bottom`	Pair of edges that trigger the start of parallax	Reuse progress geometry when coordinating multiple modules
`string-exit-el` / `string-exit-vp`	enum (`top`/`bottom`/`left`/`right`)	`bottom` / `top`	Pair that signals completion	Set both to `bottom` for long-running backgrounds
`string-copy-from`	string	—	Mirrors another parallax element by `string-id`	Ideal for splitting layers that must remain in phase

Offset attributes support the same syntax as the progress module. See Offset Concepts for unit combinations and visual examples.

Module Snapshot

Activation attribute: string="parallax"
Transform applied: inline translate3d(0, …px, 0) each frame
Event channel: object:parallax:<id> (emits the current translation in pixels)
Internals: inherits all StringProgress geometry, easing, and mirror behaviour
Responsive note: automatically falls back to zero movement on viewports ≤ 1080 px wide

Basic Usage

import StringTune, { StringParallax } from '@fiddle-digital/string-tune';

const stringTune = StringTune.getInstance();
stringTune.use(StringParallax);
stringTune.start(60);

<div string="parallax" string-id="hero-layer" string-parallax="0.35" class="hero__layer">…</div>

Tip: wrap the moving element if you need additional transforms or filters—StringParallax will override the element’s own transform property.

How It Works

Progress foundation: inherits the progress calculation (progress-raw, easing, thresholds) from StringProgress.
Strength calibration: absolute string-parallax value scales travel distance; sign determines direction.
Bias window: string-parallax-bias redistributes the movement so the element can lead or lag the viewport scroll.
Auto offsets: on init the module inflates string-offset-top/bottom by the viewport height times strength, providing headroom without manual tuning.
Frame updates: during onScrollMeasure it computes translation and stores it on the object; onMutate writes translate3d to the element and any mirrors via styleTxn.
Mobile fallback: when the responsive breakpoint switches to mobile, translation snaps to zero and event payloads emit 0.

Event Signal

Channel pattern	Payload	Fired when	Use cases
`object:parallax:<id>`	`{ translateY: number }`	Calculated translation changes on scroll	Sync WebGL depth planes, adjust atmospheric haze, relay values to analytics

stringTune.on('object:parallax:hero-layer', ({ translateY }) => {
  // feed translation into shader uniforms or complementary DOM layers
});

StringParallax gives scroll scenes cinematic depth—dial the strength, tailor the bias, and layer additional modules on top for interactive narratives.