StringTune API

Instance access

const stringTune = StringTune.getInstance();

Use the shared singleton instance unless your package design explicitly changes that assumption.

Core methods

use(Module, options?)

Registers a built-in or custom module.

setupSettings(settings)

Sets global runtime settings such as offsets, cursor lerp, loading timeout, and related defaults.

start(fps?)

Starts the runtime loop and initializes the current DOM state.

on(name, callback) / off(name, callback?)

Subscribes to or unsubscribes from supported global event channels.

scrollTo(...)

Scrolls via the active scroll controller. This is the supported public scroll API.

Supported call forms:

stringTune.scrollTo(640);
stringTune.scrollTo('#pricing');
stringTune.scrollTo(document.querySelector('#pricing') as HTMLElement);

stringTune.scrollTo({ position: 640 });
stringTune.scrollTo({ position: 640, immediate: true });
stringTune.scrollTo({ position: 640, offset: -80 });

stringTune.scrollTo({ selector: '#pricing' });
stringTune.scrollTo({ selector: '#pricing', offset: -80 });

stringTune.scrollTo({ element: pricingElement });
stringTune.scrollTo({ element: pricingElement, immediate: true, offset: -80 });

Behavior notes:

• immediate defaults to false
• offset is added to the resolved position
• offset is available on object forms only
• string targets are treated as CSS selectors
• if the selector or element cannot be resolved, the call becomes a no-op

invalidateCenter(id)

Invalidates the cached center for a specific object id. Call this after a DOM change that moves one element so the runtime recomputes its position on the next frame.

stringTune.invalidateCenter('my-element-id');

Note: The older invalidateCenters() method (plural, no argument) was removed in v1.1.51. For bulk DOM changes, use onResize(true) instead.

onResize(force?)

Triggers a full layout rebuild. Pass true to force a complete recomputation regardless of whether dimensions appear to have changed.

stringTune.onResize(true);

This is the correct replacement for invalidateCenters() when you need to recompute all positions at once — for example after injecting content or rearranging elements programmatically.

registerScrollMode(name, controller)

Registers a custom scroll controller.

Public properties

Commonly consumed properties include:

• scrollDesktopMode
• scrollMobileMode
• speed
• speedAccelerate
• scrollPosition

scrollPosition is an immediate runtime setter. It does not behave like a built-in animated scrollTo.

Not part of the public contract

• private runtime managers
• bracket access into private fields
• undocumented internal caches and observers