Scroll Modes

Built-in modes

• smooth
• default
• disable

Defaults

Current runtime defaults are:

• desktop: smooth
• mobile: default

Tuning smooth scroll

Smooth-scroll feel is controlled by public instance properties, not by setupSettings(...).

const stringTune = StringTune.getInstance();

stringTune.scrollDesktopMode = "smooth";
stringTune.scrollMobileMode = "default";

stringTune.speed = 0.1;
stringTune.speedAccelerate = 0.5;

speed

Controls how fast the current scroll position catches up to the target position on each frame.

• lower value: more smoothing, more lag, softer motion
• higher value: less smoothing, more direct motion
• runtime default: 0.1

speedAccelerate

Controls how aggressively wheel delta is converted into target movement.

• lower value: weaker impulse, calmer motion
• higher value: stronger impulse, more reactive motion
• accepted public input: normalized value from 0 to 1
• runtime mapping: 0 becomes 0.1, 1 becomes 0.5
• practical middle point: 0.5 maps to 0.3

Practical presets

// softer / smoother
stringTune.speed = 0.07;
stringTune.speedAccelerate = 0.25;

// balanced
stringTune.speed = 0.1;
stringTune.speedAccelerate = 0.5;

// tighter / more direct
stringTune.speed = 0.16;
stringTune.speedAccelerate = 0.8;

If you are looking for a setupSettings({ ... }) key for scroll smoothness, there is currently no equivalent public setting key. Use these instance properties instead.

Responsive switching

The built-in responsive mode decision is width-based. It is not documented as a generic touch-device detector.

Mode-scoped activation

By default, a module key like string="lerp" inherits the module's own defaultModeScope. Some built-in modules — StringLerp, StringGlide, StringParallax — scope themselves to smooth mode only, so they connect and disconnect automatically as the scroll mode changes.

You can override this per-element using bracket syntax on the string attribute:

This syntax works with any module key and can be combined with other keys on the same element:

<!-- lerp active only in smooth, parallax active in all modes -->
<div string="lerp[smooth]|parallax[]" string-id="hero"></div>

When the scroll mode changes at runtime, objects that no longer match the active mode are automatically disconnected. Objects that match are automatically reconnected. Managed CSS variables and transforms are cleared on disconnect.

Custom modes

Use registerScrollMode() with a ScrollController implementation when you need to integrate a custom scroll engine.

Public guidance

Document the supported mode names, how to switch them, and what scroll controller path is public. Do not document internal scroll manager details as consumer API.