Rolagem suave com Lenis
O Lenis intercepta a entrada da roda do mouse e suaviza a posição nativa do scroll. O posicionamento fixo (sticky),
IntersectionObserver e window.scrollY continuam funcionando — é por isso que é a
escolha certa. As falhas vêm de coisas que lutam contra ele, não do Lenis em si.
Configuração
Vincule-o localmente em vez de usar um link direto de CDN, para que o site fique autocontido e funcione a partir de
file://:
curl -sSL -o assets/vendor/lenis.min.js https://unpkg.com/[email protected]/dist/lenis.min.js
A versão dist/lenis.min.js é uma IIFE que expõe globalThis.Lenis — funciona bem em uma
<script> simples. (dist/lenis.mjs é ESM e não funcionará em uma tag script comum.)
Carregue-a antes do seu próprio 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, // deixa o toque nativo — suavizá-lo parece lento em celulares
autoRaf: true, // Lenis executa seu próprio loop RAF; sem necessidade de ticker manual
anchors: { offset: -(navH + 10) } // links internos ultrapassam o cabeçalho fixo
});
} else {
// sem Lenis — devolve ao navegador seu comportamento padrão
document.documentElement.style.scrollBehavior = reduced ? 'auto' : 'smooth';
}
CSS obrigatório
html { /* NÃO usar scroll-behavior: smooth — ele conflita com o 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 no html deve ser removido. Se mantido, os saltos de âncora fazem animação dupla
e entram em conflito com a suavização.
Armadilha 1 — overflow: clip destrói position: sticky
Esta é a que vai te custar uma hora.
lenis.stop() adiciona a classe .lenis-stopped, cujo CSS define overflow: clip no <html>. Isso
remove a área de rolagem, e position: sticky não tem mais onde se fixar — elementos sticky
voltam para sua posição no documento, ou seja, o topo da página.
Ao abrir um menu no scroll 1200, seu cabeçalho fixo aparece em top: -1200. Fora da tela.
Junto com o botão de fechar. Usuários relatam como "o botão de fechar desapareceu".
O mesmo acontece com o bloqueio clássico de rolagem com body { position: fixed }, pelo
mesmo motivo — sem área de rolagem.
Correção: fixe o cabeçalho na janela de visualização enquanto a rolagem estiver bloqueada.
html.menu-open .nav-wrap { position: fixed; top: 0; left: 0; right: 0; }
document.documentElement.classList.toggle('menu-open', open);
Altere a classe enquanto a sobreposição ainda está opaca para que a mudança de layout sticky→fixed seja invisível. Aplique-a tanto no caminho com Lenis quanto no caminho de movimento reduzido.
Teste sobreposições em um deslocamento de scroll diferente de zero. No scroll 0, um cabeçalho sticky quebrado é pixel-idêntico a um funcional, então o bug se esconde completamente. Verifique em 0, ~1200 e no fundo da página.
Armadilha 2 — não acumule dois bloqueios de rolagem
Fixar o corpo e chamar lenis.stop() faz com que eles entrem em conflito: position: fixed no corpo
colapsa a altura da página, o Lenis resincroniza para 0 e, ao fechar a sobreposição, o usuário é jogado no
topo da página.
Com o Lenis, stop() mais seu próprio overflow: clip mantém a página sem tocar no corpo
— assim a posição do scroll nunca é perdida e não há nada para restaurar:
if (lenis) {
open ? lenis.stop() : lenis.start();
} else if (open) { // apenas no caminho de movimento reduzido
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);
}
Verifique: role até 1200 → abra → gire a roda → feche. A posição deve ser 1200 em cada etapa, e a rolagem deve funcionar novamente depois.
Armadilha 3 — links de âncora
O Lenis controla a rolagem, então links puros href="#id" parecem estranhos. Use a opção interna
anchors com deslocamento negativo igual à altura do seu cabeçalho fixo, ou direcione os cliques
manualmente através de lenis.scrollTo(target, { offset: -navH }).
Verifique a posição final: o topo da seção deve ficar na borda inferior do cabeçalho ou abaixo dela, não escondido atrás dele.
Armadilha 4 — Lenis geralmente não é a causa do seu jank
Quando o scroll parece ruim após adicionar o Lenis, meça antes de culpá-lo. Em uma montagem, o scroll nativo realmente apresentou desempenho pior (13% de quadros perdidos vs 9%) — o Lenis estava bem e os custos reais estavam em outros lugares:
- uma sobreposição fixa em tela cheia com
mix-blend-mode(grão de filme): 34% → 3% de quadros perdidos apenas removendo o modo de mesclagem backdrop-filterem um elemento fixo, que fica na tela em cada quadro de cada rolagembackdrop-filterem elementos grandes em geral — ele reamostra a cada quadro
Medição de quadros
// na página
window.__f = []; let l = performance.now();
const t = n => { window.__f.push(n - l); l = n; requestAnimationFrame(t); };
requestAnimationFrame(t);
Alimente com eventos reais de roda do mouse na seção suspeita e reporte a média, o p95 e a
porcentagem de quadros > 33ms. Divida e conquiste desativando um efeito de cada vez com
add_style_tag. Um resultado saudável é ~16,7ms de média e 0% de quadros longos; qualquer coisa acima de ~10%
de quadros longos indica travamento visível.
Checklist
-
scroll-behavior: smoothremovido dohtml - Bloco CSS do Lenis adicionado
-
autoRaf: true(ou um loop RAF manual — não ambos) - Deslocamento
anchorsigual à altura do cabeçalho fixo -
syncTouch: falsepara que celulares mantenham o momentum nativo - Cabeçalhos fixos enquanto qualquer sobreposição bloquear a rolagem
- Apenas um mecanismo de bloqueio de rolagem ativo
- Sobreposições testadas em um deslocamento de scroll diferente de zero
-
prefers-reduced-motiondesvia do Lenis e restaura o comportamento nativo - Posição do scroll preservada ao abrir → fechar
- Tempo dos quadros medido, não presumido