StringMagnetic

StringMagnetic pulls an element toward the pointer when the pointer comes within a configured radius. The module does not apply any transform by itself. It only writes CSS variables and emits movement events.

Public API

Attributes

Attribute	Type	Default	Real runtime effect
`string-strength`	number	`0.3`	Scales how far the element can be pulled toward the pointer.
`string-radius`	number	`150`	Defines the active zone around the element center. Outside this radius the module stays idle.

CSS Variables and DOM Output

The module writes these CSS variables on the source element and all mirrors:

--magnetic-x
--magnetic-y

Both values are plain numbers. Add units yourself in CSS, usually with * 1px.

Events

Channel	Payload	Fired when
`magnetic:move:<id>`	`{ x, y }`	The smoothed magnetic offset changes

Mirror Behavior

When the source object has mirrors via string-copy-from, the source and all mirrors receive the same --magnetic-x and --magnetic-y values.

Quick Example

HTML

<header class="header">
  <div class="logo">Fiddle</div>
  <button
    string="magnetic"
    string-id="magnetic-btn"
    string-strength="0.4"
    string-radius="150"
    class="magnetic-btn"
  >
    <span class="btn-text">Contact Us</span>
  </button>
</header>

CSS

.header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 1.5rem 2rem;
  border-bottom: 1px solid black;
}

.logo {
  font-weight: bold;
  font-size: 1.25rem;
}

.magnetic-btn {
  padding: 0.75rem 1.75rem;
  border: 1px solid black;
  border-radius: 999px;
  background: white;
  color: black;
  cursor: pointer;
  transform: translate3d(
    calc(var(--magnetic-x, 0) * 1px),
    calc(var(--magnetic-y, 0) * 1px),
    0
  );
}

Registration

TypeScript

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

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

StringCursor is not required for StringMagnetic. The module uses the shared pointer data already tracked by StringTune.

Detailed Behavior

StringMagnetic uses a fixed internal smoothing factor of 0.1. There is no public attribute for changing that in the current build.
The module registers CSS properties for --magnetic-target-x and --magnetic-target-y, but the current runtime does not write those values. They should not be documented as public output.
The module does not mutate the element transform property for you. Always consume the variables in your own CSS.