O Lenis, desenvolvido pela Darkroom Engineering, é uma biblioteca de scroll suave (smooth scroll) extremamente leve e performática, focada em navegadores modernos. Diferente de outras soluções mais pesadas, ele foi projetado para oferecer uma integração fluida com efeitos de parallax e sincronização de animações WebGL, mantendo a acessibilidade e o comportamento nativo do navegador sob controle.

Integração e Configuração Inicial

A biblioteca pode ser adicionada ao projeto de duas formas principais. A recomendada para fluxos de trabalho modernos é através de gerenciadores de pacotes:

npm install lenis

Para projetos que não utilizam build tools, é possível carregar a biblioteca via CDN diretamente no HTML:

<script src="https://unpkg.com/lenis@1.1.18/dist/lenis.min.js"></script>

Instanciando o Motor de Scroll

Diferente de scrolls nativos, o Lenis exige que você gerencie o ciclo de atualização das animações através do método requestAnimationFrame. Abaixo, apresentamos uma estrutura robusta para inicializar o motor e capturar eventos de rolagem:

import Lenis from 'lenis';

// Inicialização com configurações customizadas
const smoothScroll = new Lenis({
  duration: 1.5,
  easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)),
  orientation: 'vertical',
  gestureOrientation: 'vertical',
  smoothWheel: true,
});

// Listener para monitoramento de posição
smoothScroll.on('scroll', (event) => {
  const { scroll, limit, velocity, progress } = event;
  // Lógica para parallax ou gatilhos de animação
});

// Loop de execução frame-a-frame
function scrollUpdate(time) {
  smoothScroll.raf(time);
  requestAnimationFrame(scrollUpdate);
}

requestAnimationFrame(scrollUpdate);

Ajustes Necessários de CSS

Para garantir que o comportamento do scroll suave não entre em conflito com as propriedades padrões do navegador ou cause "saltos" visuais, é essencial aplicar certas regras no seu arquivo de estilos global:

html.lenis,
html.lenis body {
  height: auto;
}

.lenis.lenis-smooth {
  scroll-behavior: auto !important;
}

.lenis.lenis-smooth [data-lenis-prevent] {
  overscroll-behavior: contain;
}

.lenis.lenis-stopped {
  overflow: hidden;
}

.lenis.lenis-scrolling iframe {
  pointer-events: none;
}

Resolução de Problemas Comuns

Conflito com Scroll nativo do Navegador

Se você notar um efeito de "tremido" ou se o scroll suave parecer estar lutando contra o scroll padrão, verifique se a propriedade scroll-behavior: smooth; está ativada no seu CSS. O Lenis exige que o scroll-behavior seja definido como auto para que ele possa interceptar e suavizar o movimento corrretamente.

Scroll em Elementos de Overflow (Modais e Menus)

Em componentes que possuem seu próprio scroll (como janelas modais), o Lenis pode tentar controlar a página ao fundo simultaneamente. Para evitar isso, adicione o atributo data-lenis-prevent ao elemento container do modal. Isso instrui a biblioteca a ignorar os eventos de rolagem disparados dentro daquela área específica.

Links Quebrados e Documentação

Ao procurar por soluções em issues antigas do repositório, você pode encontrar páginas de erro 404. Isso geralmente ocorre devido à migração de versões ou reestruturação da organização no GitHub. A recomendação técnica é sempre consultar a documantação oficial no repositório da darkroomengineering/lenis para obter as assinaturas de métodos mais recentes, já que a API evoluiu significativamente nas últimas atualizações.