Défilement fluide avec Lenis
Lenis intercepte les entrées de la molette et adoucit la position de défilement native. Le positionnement sticky,
IntersectionObserver et window.scrollY continuent de fonctionner — c'est pourquoi c'est le
bon choix. Les échecs viennent de choses qui le combattent, pas de Lenis lui-même.
Configuration
Vendez-le plutôt que de faire un lien direct vers un CDN, afin que le site reste autonome et fonctionne depuis
file:// :
curl -sSL -o assets/vendor/lenis.min.js https://unpkg.com/[email protected]/dist/lenis.min.js
La version dist/lenis.min.js est une IIFE qui expose globalThis.Lenis — parfait dans une simple
balise <script>. (dist/lenis.mjs est en ESM et ne fonctionnera pas dans une balise script standard.)
Chargez-la avant votre propre 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, // laissez le tactile natif — le lisser donne une sensation de latence sur mobile
autoRaf: true, // Lenis gère sa propre boucle RAF ; pas besoin de ticker manuel
anchors: { offset: -(navH + 10) } // les liens internes évitent l'en-tête sticky
});
} else {
// pas de Lenis — redonnez au navigateur son comportement par défaut
document.documentElement.style.scrollBehavior = reduced ? 'auto' : 'smooth';
}
CSS requis
html { /* PAS de scroll-behavior: smooth — cela entre en conflit avec 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 sur html doit être supprimé. Si vous le conservez, les sauts d'ancres
s'animeront deux fois et entreront en conflit avec l'easing.
Piège n°1 — overflow: clip tue position: sticky
C'est celui qui vous coûtera une heure.
lenis.stop() ajoute .lenis-stopped, dont le CSS définit overflow: clip sur <html>. Cela
supprime le scrollport, et position: sticky n'a plus rien à quoi se rattacher — les éléments
sticky reviennent à leur position dans le document, c'est-à-dire le haut de la page.
Ouvrez un menu à un défilement de 1200 et votre en-tête sticky s'affiche à top: -1200. Hors écran.
Avec son bouton de fermeture. Les utilisateurs signalent « le bouton de fermeture a disparu ».
Le même phénomène se produit avec le verrouillage de défilement classique body { position: fixed },
pour la même raison — pas de scrollport.
Correctif : épinglez l'en-tête à la fenêtre tant que le défilement est verrouillé.
html.menu-open .nav-wrap { position: fixed; top: 0; left: 0; right: 0; }
document.documentElement.classList.toggle('menu-open', open);
Basculez la classe pendant que le calque est encore opaque pour que le changement de sticky à fixed soit invisible. Appliquez-la à la fois sur le chemin Lenis et sur le chemin réduit-mouvement.
Testez les calques à un décalage de défilement non nul. À un défilement de 0, un en-tête sticky cassé est pixel-identique à un en-tête fonctionnel, donc le bug se cache complètement. Vérifiez à 0, ~1200, et en profondeur dans la page.
Piège n°2 — ne pas cumuler deux verrous de défilement
Épingler le corps et appeler lenis.stop() les fait se battre : position: fixed sur le corps
réduit la hauteur de la page, Lenis se resynchronise à 0, et la fermeture du calque ramène
l'utilisateur en haut de la page.
Avec Lenis, stop() plus son propre overflow: clip maintient la page sans toucher au corps
— ainsi la position de défilement n'est jamais perdue et il n'y a rien à restaurer :
if (lenis) {
open ? lenis.stop() : lenis.start();
} else if (open) { // chemin réduit-mouvement uniquement
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);
}
Vérifiez : faites défiler jusqu'à 1200 → ouvrez → molette → fermez. La position doit lire 1200 à chaque étape, et le défilement doit refonctionner ensuite.
Piège n°3 — ancres de page
Lenis contrôle le défilement, donc les sauts bruts href="#id" semblent incorrects. Utilisez
l'option intégrée anchors avec un décalage négatif égal à la hauteur de votre en-tête sticky, ou
acheminez les clics manuellement via lenis.scrollTo(target, { offset: -navH }).
Vérifiez la position d'arrivée : le haut de la section doit se trouver au niveau ou en dessous du bord inférieur de l'en-tête, pas en dessous de celui-ci.
Piège n°4 — Lenis n'est généralement pas la cause du ralentissement
Lorsque le défilement semble mauvais après avoir ajouté Lenis, mesurez avant de l'accuser. Dans un projet, le défilement natif mesurait en fait pire (13% de trames perdues contre 9%) — Lenis allait bien et les vrais coûts étaient ailleurs :
- un calque fixe plein écran avec
mix-blend-mode(grain de film) : 34% → 3% de trames perdues rien qu'en supprimant le mode de fusion backdrop-filtersur un élément sticky, qui est affiché à chaque trame de chaque défilementbackdrop-filtersur de grands éléments en général — il ré-échantillonne par trame
Harness de mesure des trames
// dans la page
window.__f = []; let l = performance.now();
const t = n => { window.__f.push(n - l); l = n; requestAnimationFrame(t); };
requestAnimationFrame(t);
Pilotez-le avec de vrais événements de molette sur la section suspecte, puis rapportez la moyenne,
le p95 et le pourcentage de trames > 33 ms. Divisez pour régner en désactivant un effet à la fois
avec add_style_tag. Un état sain a une moyenne d'environ 16,7 ms et 0 % de trames longues ;
tout ce qui dépasse ~10 % de trames longues est un bégaiement visible.
Liste de contrôle
-
scroll-behavior: smoothsupprimé dehtml - Bloc CSS Lenis ajouté
-
autoRaf: true(ou une boucle RAF manuelle — pas les deux) - Le décalage
anchorscorrespond à la hauteur de l'en-tête sticky -
syncTouch: falsepour que les téléphones conservent le momentum natif - Les en-têtes sticky sont épinglés pendant qu'un calque verrouille le défilement
- Un seul mécanisme de verrouillage de défilement actif
- Les calques sont testés à un décalage de défilement non nul
-
prefers-reduced-motionignore Lenis et restaure le comportement natif - La position de défilement est conservée lors de l'ouverture → fermeture
- Les performances des trames sont mesurées, pas supposées