Skip to content
back

Known limitations

These notes describe the 1.0 API and its integration constraints.

  • Core services are singletons and require the browser DOM. There is no complete public destroy operation.

  • Smooth scrolling uses Lenis defaults; the retained smooth.inertia setting has no effect.

  • Failed navigation fetches fall back to normal document navigation. Overlapping transition requests are serialized: the active transition finishes, then only the latest queued destination starts. A request that never settles still has no built-in timeout.

  • Animations that write the same inline transform should be placed on separate wrappers.

  • Automatic reduced-motion handling is not a library-wide behavior. Configure your integration explicitly; the documentation homepage disables decorative motion for that preference.

  • When loading Lottie later with deferInit(), avoid id="lottie" on HTML elements: browsers expose named elements on window, which can shadow the absent player global.

  • Custom text-splitting animations should wait for their fonts before measuring lines. Luge does not automatically wait for web fonts or third-party animations.

  • Lottie lazy loading and required page-loading gates should not be combined. Lottie preloaders and transition loaders need their player global before initialization; their loading failures do not use LottiePlayer’s lottieerror handling.

RC-to-1.0 compatibility

Keep the same plugin names, settings() calls, attributes and callback signatures. Named imports still require explicit registration before init(); the UMD build registers the bundled plugins automatically. Both dist/luge.umd.js and dist/js/luge.umd.js remain available. The CSS import @waaark/luge/css is an additional convenience entry point.

The 1.0 changes preserve native modified-click/download behavior and Forward history, serialize overlapping transitions, cancel pending reveals and retired-player loop work at page cleanup, and support plain slide as an alias of slide-to-top for preloaders and loaders. Animation formulas, default settings and singleton service ownership are retained.