StringMagnetic Module

Simulate a “magnetised” hover zone that nudges elements toward the pointer. StringMagnetic measures cursor distance every frame, computes a pull factor, and feeds the result into CSS variables you can animate against.

Activation primer: Add string="magnetic" to every element you want StringMagnetic to influence. 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-strength`	number	`0.3`	Scale applied to the magnetic pull (0 disables, >1 amplifies)	Negative values invert the effect, pushing elements away
`string-radius`	number	`150`	Radius in pixels from the element centre where the pull is active	Larger radii cover more of the viewport; tune per component
`string-target-disable`	boolean	`false`	Prevents this element from reacting even if marked with `string="magnetic"`	Handy for nested targets that should remain static
`string-target-style-disable`	boolean	`false`	Stops the module from writing `--magnetic-x` / `--magnetic-y`	Use when you only consume the emitted events

Module Snapshot

Activation attribute: string="magnetic"
CSS variables populated: --magnetic-x, --magnetic-y (pixels)
Event channel: magnetic:move:<id> → { x, y } (pixels)
Pointer dependency: responds to real-time mouse movement (desktop only recommended)
Smoothing: internal lerp (≈0.1) keeps motion fluid; snaps when displacement is negligible

Basic Usage

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

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

<button string="magnetic" string-id="buy-cta" string-radius="220" string-strength="0.45" class="cta">Add to cart</button>

.cta {
  transform: translate(calc(var(--magnetic-x, 0) * 1px), calc(var(--magnetic-y, 0) * 1px));
  transition: box-shadow 0.15s ease;
}

How It Works

Distance sampling: each mouse move calculates the cursor vector from element centre, then calls the magnetic pull tool to get a strength factor (0→1). The factor is scaled by string-strength.
Target storage: results become target offsets (magnetic-target-x/y). Only elements inside the radius flip is-magneting to true.
Lerped motion: during the animation frame loop the module lerps current values toward their targets, snapping when within ±0.01 px.
CSS sync: unless string-target-style-disable is set, the module writes the offsets into --magnetic-x/--magnetic-y for the element and any mirrors declared via string-copy-from.
Auto reset: when the target equals the current values the magnetic state disengages, keeping updates quiet until the pointer re-enters.

Event Signal

Channel pattern	Payload	Fired when	Use cases
`magnetic:move:<id>`	`{ x: number; y: number; }`	Lerp’d offsets change during a frame	Drive complementary DOM layers, spring presets, or audio pan effects

stringTune.on('magnetic:move:buy-cta', ({ x, y }) => {
  // x/y already in pixels; blend with canvas overlays or analytics events
});

StringMagnetic adds tactile hover feedback—dial the radius, set the pull strength, and let CSS or JavaScript translate those offsets into expressive motion.