Lenis Smooth Scroll
Lenis fängt Radeingaben ab und gleicht die native Scroll-Position weich aus. Sticky-Positionierung,
IntersectionObserver und window.scrollY funktionieren weiterhin — weshalb es die richtige
Wahl ist. Die Fehler kommen von Dingen, die dagegen ankämpfen, nicht von Lenis selbst.
Einrichtung
Binde die Bibliothek als lokale Datei ein, anstatt einen CDN-Link zu verwenden, damit die Seite in sich geschlossen bleibt und auch von file:// funktioniert:
curl -sSL -o assets/vendor/lenis.min.js https://unpkg.com/[email protected]/dist/lenis.min.js
Der Build dist/lenis.min.js ist ein IIFE, der globalThis.Lenis bereitstellt — funktioniert in einem einfachen
<script>-Tag. (dist/lenis.mjs ist ESM und wird nicht in einem einfachen Script-Tag funktionieren.)
Lade es vor deinem eigenen Script.
var reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
var lenis = null;
if (!reduced && window.Lenis) {
var navH = parseInt(getComputedStyle(document.documentElement)
.getPropertyValue('--nav-h'), 10) || 0;
lenis = new Lenis({
duration: 1.05,
easing: t => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
smoothWheel: true,
syncTouch: false, // Touch bleibt nativ — Glättung fühlt sich auf Handys träge an
autoRaf: true, // Lenis hat eine eigene RAF-Schleife; kein manueller Ticker nötig
anchors: { offset: -(navH + 10) } // Interne Links lassen den Sticky-Header frei
});
} else {
// Kein Lenis — dem Browser sein eigenes Verhalten zurückgeben
document.documentElement.style.scrollBehavior = reduced ? 'auto' : 'smooth';
}
Erforderliches CSS
html { /* KEIN scroll-behavior: smooth — es kämpft gegen Lenis */ }
html.lenis, html.lenis body { height: auto; }
.lenis:not(.lenis-autoToggle).lenis-stopped { overflow: clip; }
.lenis.lenis-smooth [data-lenis-prevent] { overscroll-behavior: contain; }
.lenis.lenis-smooth iframe { pointer-events: none; }
scroll-behavior: smooth auf html muss entfernt werden. Wenn es bleibt, animieren Anchor-Sprünge doppelt und kämpfen gegen die Glättung.
Falle 1 — overflow: clip tötet position: sticky
Das ist die Falle, die dich eine Stunde kostet.
lenis.stop() fügt .lenis-stopped hinzu, dessen CSS overflow: clip auf <html> setzt. Das
entfernt den Scrollport, und position: sticky hat nichts mehr, woran es haften kann — Sticky-Elemente
schnappen zurück an ihre Position im Dokument, also an den oberen Rand der Seite.
Öffnet man ein Menü bei Scroll-Position 1200, wird der Sticky-Header bei top: -1200 dargestellt. Außerhalb des Bildschirms.
Zusammen mit seinem Schließen-Button. Nutzer berichten: „Der Schließen-Button ist verschwunden.“
Dasselbe passiert mit der klassischen body { position: fixed }-Scroll-Sperre, aus demselben Grund — kein Scrollport.
Lösung: Fixiere den Header für die Dauer der gesperrten Scroll-Position im Viewport.
html.menu-open .nav-wrap { position: fixed; top: 0; left: 0; right: 0; }
document.documentElement.classList.toggle('menu-open', open);
Füge die Klasse hinzu, während das Overlay noch deckend ist, damit der Wechsel von Sticky zu Fixed unsichtbar bleibt. Wende sie auf beiden Pfaden an (Lenis und reduzierte Bewegung).
Teste Overlays bei einer Scroll-Position ungleich Null. Bei Scroll-Position 0 ist ein defekter Sticky-Header pixelgenau identisch mit einem funktionierenden, sodass der Fehler vollständig versteckt bleibt. Überprüfe bei 0, ~1200 und tief in der Seite.
Falle 2 — nicht zwei Scroll-Sperren stapeln
Das Fixieren des Bodys und das Aufrufen von lenis.stop() führt zu Konflikten: position: fixed auf dem Body
lässt die Seitenhöhe kollabieren, Lenis synchronisiert zurück auf 0, und beim Schließen des Overlays wird der Benutzer
an den oberen Rand der Seite geworfen.
Mit Lenis hält stop() plus das eigene overflow: clip die Seite ohne den Body zu berühren —
also geht die Scroll-Position nie verloren und es gibt nichts wiederherzustellen:
if (lenis) {
open ? lenis.stop() : lenis.start();
} else if (open) { // nur bei reduzierter Bewegung
scrollY = window.scrollY;
document.body.style.position = 'fixed';
document.body.style.top = -scrollY + 'px';
document.body.style.width = '100%';
} else if (document.body.style.position === 'fixed') {
document.body.style.position = '';
document.body.style.top = '';
document.body.style.width = '';
window.scrollTo(0, scrollY);
}
Überprüfe: Scrolle auf 1200 → öffne → scrolle → schließe. Die Position muss bei jedem Schritt 1200 betragen, und Scrollen muss danach wieder funktionieren.
Falle 3 — Anchor-Links
Lenis steuert das Scrollen, daher sehen rohe href="#id"-Sprünge falsch aus. Verwende die eingebaute
anchors-Option mit einem negativen Offset in Höhe deines Sticky-Headers oder leite Klicks manuell
über lenis.scrollTo(target, { offset: -navH }).
Überprüfe die Zielposition: Der Abschnittsanfang muss auf oder unter der Unterkante des Headers liegen, nicht darunter.
Falle 4 — Lenis ist normalerweise nicht dein Ruckeln
Wenn sich das Scrollen nach dem Hinzufügen von Lenis schlecht anfühlt, messe bevor du es beschuldigst. In einem Build war das native Scrollen tatsächlich schlechter (13% verlorene Frames vs. 9%) — Lenis war in Ordnung und die eigentlichen Kosten lagen woanders:
- ein fixiertes, vollbildgroßes
mix-blend-mode-Overlay (Filmkörnung): 34% → 3% verlorene Frames allein durch Entfernen des Blend-Modus backdrop-filterauf einem Sticky-Element, das bei jedem Frame jedes Scrollvorgangs auf dem Bildschirm istbackdrop-filterauf großen Elementen im Allgemeinen — es wird pro Frame neu berechnet
Frame-Timing-Werkzeug
// in der Seite
window.__f = []; let l = performance.now();
const t = n => { window.__f.push(n - l); l = n; requestAnimationFrame(t); };
requestAnimationFrame(t);
Treiben Sie es mit echten Radeingaben über den verdächtigen Bereich an und melden Sie dann Mittelwert, p95 und den
Prozentsatz der Frames > 33ms. Durch Versuch und Irrtum deaktivieren Sie einen Effekt nach dem anderen mit
add_style_tag. Gesund ist ~16,7ms Mittelwert und 0% lange Frames; alles über ~10% lange Frames ist sichtbares Ruckeln.
Checkliste
-
scroll-behavior: smoothvonhtmlentfernt - Lenis-CSS-Block hinzugefügt
-
autoRaf: true(oder eine manuelle RAF-Schleife — nicht beides) -
anchors-Offset entspricht der Höhe des Sticky-Headers -
syncTouch: false, damit Handys natives Momentum behalten - Sticky-Header fixiert, während ein Overlay das Scrollen sperrt
- Nur ein Scroll-Sperr-Mechanismus aktiv
- Overlays bei einer von Null verschiedenen Scroll-Position getestet
-
prefers-reduced-motionüberspringt Lenis und stellt natives Verhalten wieder her - Scroll-Position über Öffnen → Schließen erhalten
- Frame-Timing gemessen, nicht angenommen