Advanced Configuration

StringTune ships with sensible defaults, but you can tailor scroll behaviour, module fallbacks, and runtime tuning through a small set of APIs. This guide documents the configuration surface that exists in the current build.

Global Defaults with setupSettings

Call stringTune.setupSettings() once before starting the engine to provide fallback values that every module can reference. Attribute values in the DOM still win, so this is ideal for theming, spacing presets, or mobile tweaks.

import StringTune from '@fiddle-digital/string-tune';

const stringTune = StringTune.getInstance();

stringTune.setupSettings({
  'offset-top': '-10%',
  'offset-bottom': '-10%',
  parallax: 0.25,
  lerp: 0.8,
  glide: 0.75,
  repeat: 'true',
});

stringTune.start(60);

Layout & Activation Keys

Viewport Timing Keys

Scroll & Motion Keys

Cursor, Magnetic & Spotlight Keys

Impulse (Physics) Keys

System & Loading Keys

Pass values exactly as you would in HTML attributes ('20%', '4rem', 'true', numeric literals, etc.).

Runtime Tweaks

Scroll Dynamics

const stringTune = StringTune.getInstance();
stringTune.speed = 0.14;
stringTune.speedAccelerate = 0.32;

Manual Scroll Control

You rarely need to touch these directly, but they are available for custom scroll syncing.

• stringTune.scrollPosition = 640; — sets the internal scroll state; the scroll manager will animate to this point.
• stringTune.scrollTo(position: number) — helper that forwards to the active scroll strategy.
• stringTune.scrollToElement(selector: string, offset = 0) — convenience wrapper for element targeting.

await nextTick();
stringTune.scrollToElement('#pricing', 120);

Recomputing Layout

• stringTune.onResize(true) — force a rebuild of measurements, offsets, and responsive settings.
• stringTune.invalidateCenters() — flush cached element centers; useful after DOM transforms that do not change size.

watch(posts, async () => {
  await nextTick();
  stringTune.onResize(true);
  stringTune.invalidateCenters();
});

There is no generic stringTune.onResize(true) helper in the current build; the resize pipeline above is the intended public entry point.

Teardown

stringTune.destroy() removes listeners, stops the loop, and clears module state. Handy for SPA route unloads or test suites.

Example: Theme + Scroll Preset

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

const stringTune = StringTune.getInstance();

stringTune.setupSettings({
  'offset-top': '-12vh',
  'offset-bottom': '8vh',
  parallax: 0.28,
  lerp: 0.65,
  strength: 0.4,
});

stringTune.use(StringParallax);
stringTune.use(StringMagnetic);
stringTune.use(StringProgress);

stringTune.speed = 0.12;
stringTune.speedAccelerate = 0.35;

stringTune.start(60);

Best Practices

• Set defaults once: Call setupSettings before the first use() to ensure modules pick up your values during their initial connect.
• Prefer attributes for exceptions: Keep global defaults broad and override specific cases in markup (string-offset-top="25vh").
• Rebuild deliberately: Batch DOM updates and call onResize(true) once per frame instead of triggering it repeatedly.
• Avoid restarting: Use the singleton instance; restarting the engine discards scroll inertia and can feel jarring.
• Profile tweaks: Small changes to speed or speedAccelerate drastically alter feel—test on both touchpads and wheels.