Desplazamiento suave con Lenis
Lenis intercepta la entrada de la rueda y suaviza la posición de desplazamiento nativa. El posicionamiento fijo (position: sticky), IntersectionObserver y window.scrollY siguen funcionando, por lo que es la elección correcta. Los fallos provienen de cosas que luchan contra él, no de Lenis en sí.
Configuración
Véndelo en lugar de enlazar un CDN, para que el sitio sea autónomo y funcione desde file://:
curl -sSL -o assets/vendor/lenis.min.js https://unpkg.com/[email protected]/dist/lenis.min.js
La compilación dist/lenis.min.js es un IIFE que expone globalThis.Lenis, perfecto en una etiqueta <script> simple. (dist/lenis.mjs es ESM y no funcionará en una etiqueta script normal.) Cárgalo antes de tu propio 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, // dejar el tacto nativo — suavizarlo se siente lento en teléfonos
autoRaf: true, // Lenis ejecuta su propio bucle RAF; no se necesita ticker manual
anchors: { offset: -(navH + 10) } // enlaces internos evitan el encabezado fijo
});
} else {
// sin Lenis — devolver al navegador su propio comportamiento
document.documentElement.style.scrollBehavior = reduced ? 'auto' : 'smooth';
}
CSS requerido
html { /* NO scroll-behavior: smooth — lucha contra 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 en html debe eliminarse. Si lo mantienes, los saltos de ancla se animan dos veces y luchan contra la suavización.
Trampa 1 — overflow: clip mata position: sticky
Esta es la que te costará una hora.
lenis.stop() añade .lenis-stopped, cuyo CSS establece overflow: clip en <html>. Eso elimina el viewport de desplazamiento, y position: sticky no tiene nada a lo que adherirse — los elementos fijos vuelven a su posición en el documento, es decir, la parte superior de la página.
Abre un menú en el desplazamiento 1200 y tu encabezado fijo se renderiza en top: -1200. Fuera de pantalla. Junto con su botón de cerrar. Los usuarios reportan que "el botón de cerrar desapareció".
Lo mismo ocurre con el clásico bloqueo de desplazamiento body { position: fixed }, por la misma razón: no hay viewport de desplazamiento.
Solución: fija el encabezado al viewport mientras el desplazamiento esté bloqueado.
html.menu-open .nav-wrap { position: fixed; top: 0; left: 0; right: 0; }
document.documentElement.classList.toggle('menu-open', open);
Cambia la clase mientras la superposición aún es opaca para que el cambio de diseño fijo→fijo sea invisible. Aplícalo tanto en la ruta de Lenis como en la de movimiento reducido.
Prueba las superposiciones en un desplazamiento distinto de cero. En el desplazamiento 0, un encabezado fijo roto es pixel-idéntico a uno funcional, por lo que el error se oculta por completo. Verifica en 0, ~1200 y en lo profundo de la página.
Trampa 2 — no apiles dos bloqueos de desplazamiento
Fijar el cuerpo y llamar a lenis.stop() hace que luchen: position: fixed en el cuerpo colapsa la altura de la página, Lenis se resincroniza a 0 y al cerrar la superposición el usuario termina en la parte superior de la página.
Con Lenis, stop() más su propio overflow: clip mantiene la página sin tocar el cuerpo — por lo que la posición de desplazamiento nunca se pierde y no hay nada que restaurar:
if (lenis) {
open ? lenis.stop() : lenis.start();
} else if (open) { // solo ruta de movimiento reducido
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);
}
Verifica: desplázate a 1200 → abre → rueda → cierra. La posición debe ser 1200 en cada paso, y el desplazamiento debe funcionar nuevamente después.
Trampa 3 — enlaces de anclaje
Lenis controla el desplazamiento, por lo que los saltos crudos de href="#id" se ven incorrectos. Usa la opción integrada anchors con un desplazamiento negativo igual a la altura de tu encabezado fijo, o dirige los clics manualmente a través de lenis.scrollTo(target, { offset: -navH }).
Verifica la posición de aterrizaje: la parte superior de la sección debe estar en o por debajo del borde inferior del encabezado, no debajo de él.
Trampa 4 — Lenis generalmente no es tu problema de rendimiento
Cuando el desplazamiento se siente mal después de agregar Lenis, mide antes de culparlo. En una compilación, el desplazamiento nativo realmente midió peor (13% de fotogramas perdidos frente a 9%) — Lenis estaba bien y los costos reales estaban en otro lugar:
- una superposición fija de viewport completo con
mix-blend-mode(grano de película): 34% → 3% de fotogramas perdidos solo al eliminar el modo de mezcla backdrop-filteren un elemento fijo, que está en pantalla en cada fotograma de cada desplazamientobackdrop-filteren elementos grandes en general — se vuelve a muestrear por fotograma
Herramienta de medición de tiempo de fotogramas
// en la página
window.__f = []; let l = performance.now();
const t = n => { window.__f.push(n - l); l = n; requestAnimationFrame(t); };
requestAnimationFrame(t);
Manéjala con eventos de rueda reales sobre la sección sospechosa, luego reporta la media, p95 y el porcentaje de fotogramas > 33ms. Divide y vencerás desactivando un efecto a la vez con add_style_tag. Un valor saludable es ~16.7ms de media y 0% de fotogramas largos; cualquier valor superior a ~10% de fotogramas largos es un tartamudeo visible.
Lista de verificación
-
scroll-behavior: smootheliminado dehtml - Bloque CSS de Lenis añadido
-
autoRaf: true(o un bucle RAF manual, no ambos) - El desplazamiento de
anchorscoincide con la altura del encabezado fijo -
syncTouch: falsepara que los teléfonos mantengan el impulso nativo - Encabezados fijos anclados mientras cualquier superposición bloquee el desplazamiento
- Solo un mecanismo de bloqueo de desplazamiento activo
- Superposiciones probadas en un desplazamiento distinto de cero
-
prefers-reduced-motionomite Lenis y restaura el comportamiento nativo - La posición de desplazamiento se conserva al abrir y cerrar
- El tiempo de fotogramas se mide, no se asume