Lenis 부드러운 스크롤
Lenis는 휠 입력을 가로채서 네이티브 스크롤 위치를 부드럽게 보간합니다. sticky 포지셔닝,
IntersectionObserver, window.scrollY가 모두 계속 작동합니다 — 이것이 Lenis가 올바른 선택인 이유입니다.
문제는 Lenis 자체가 아니라 Lenis와 충돌하는 것들에서 발생합니다.
설정
CDN을 직접 링크하는 대신 벤더 파일로 가져와서 사이트가 자체적으로 완결되고 file://에서도
작동하도록 합니다:
curl -sSL -o assets/vendor/lenis.min.js https://unpkg.com/[email protected]/dist/lenis.min.js
dist/lenis.min.js 빌드는 globalThis.Lenis를 노출하는 IIFE입니다 — 일반 <script> 태그에서
문제없이 사용할 수 있습니다. (dist/lenis.mjs는 ESM이며 일반 스크립트 태그에서는 작동하지 않습니다.)
자체 스크립트 전에 로드하세요.
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, // 터치는 네이티브로 남김 — 부드럽게 하면 폰에서 느리게 느껴짐
autoRaf: true, // Lenis가 자체 RAF 루프를 실행하므로 수동 티커 불필요
anchors: { offset: -(navH + 10) } // 페이지 내 링크가 고정 헤더를 피함
});
} else {
// Lenis 없음 — 브라우저에 자체 동작을 되돌려줌
document.documentElement.style.scrollBehavior = reduced ? 'auto' : 'smooth';
}
필수 CSS
html { /* NO scroll-behavior: smooth — 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; }
html에 scroll-behavior: smooth가 있으면 안 됩니다. 유지하면 앵커 점프가 이중으로 애니메이션되어
부드러운 효과와 충돌합니다.
함정 1 — overflow: clip이 position: sticky를 죽임
이게 한 시간을 날리게 할 함정입니다.
lenis.stop()은 .lenis-stopped를 추가하고, 그 CSS는 <html>에 overflow: clip을 설정합니다.
이렇게 하면 스크롤포트가 제거되고, position: sticky가 붙을 곳이 없어집니다 — sticky 요소가
문서에서의 위치, 즉 페이지 상단으로 튕겨버립니다.
스크롤 1200에서 메뉴를 열면 sticky 헤더가 top: -1200에 렌더링됩니다. 화면 밖입니다.
닫기 버튼도 함께 사라집니다. 사용자는 "닫기 버튼이 사라졌어요"라고 보고합니다.
클래식한 body { position: fixed } 스크롤 잠금에서도 같은 이유로 동일한 현상이 발생합니다 —
스크롤포트가 없기 때문입니다.
수정: 스크롤이 잠겨 있는 동안 헤더를 뷰포트에 고정합니다.
html.menu-open .nav-wrap { position: fixed; top: 0; left: 0; right: 0; }
document.documentElement.classList.toggle('menu-open', open);
오버레이가 아직 불투명한 상태에서 클래스를 전환하여 sticky→fixed 레이아웃 변경이 눈에 띄지 않도록 합니다. Lenis 경로와 축소 모션 경로 모두에 적용합니다.
0이 아닌 스크롤 오프셋에서 오버레이를 테스트하세요. 스크롤 0에서는 깨진 sticky 헤더가 정상 헤더와 픽셀 단위로 동일하므로 버그가 완전히 숨겨집니다. 0, ~1200, 그리고 페이지 깊숙한 곳에서 확인하세요.
함정 2 — 두 개의 스크롤 잠금을 쌓지 마세요
본문을 고정하고 동시에 lenis.stop()을 호출하면 서로 충돌합니다: position: fixed가
본문에 적용되면 페이지 높이가 줄어들고, Lenis가 0으로 재동기화되며, 오버레이를 닫으면 사용자가
페이지 상단으로 떨어집니다.
Lenis를 사용하면 stop()과 자체 overflow: clip이 본문을 건드리지 않고 페이지를
고정합니다 — 따라서 스크롤 위치가 절대 손실되지 않고 복원할 것도 없습니다:
if (lenis) {
open ? lenis.stop() : lenis.start();
} else if (open) { // 축소 모션 경로만
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);
}
확인: 1200까지 스크롤 → 열기 → 휠 → 닫기. 모든 단계에서 위치가 1200을 읽어야 하며, 그 후에 스크롤이 다시 작동해야 합니다.
함정 3 — 앵커 링크
Lenis가 스크롤을 소유하므로 일반 href="#id" 점프는 잘못 보입니다. 고정 헤더 높이와 같은
음수 오프셋을 가진 내장 anchors 옵션을 사용하거나, 클릭을 lenis.scrollTo(target, { offset: -navH })를
통해 수동으로 라우팅하세요.
도착 위치를 확인하세요: 섹션 상단이 헤더 하단 가장자리 아래에 위치해야 하며, 그 아래에 숨겨지면 안 됩니다.
함정 4 — 일반적으로 Lenis가 버벅거림의 원인이 아닙니다
Lenis를 추가한 후 스크롤이 나빠졌을 때, 먼저 측정하고 비난하기 전에 확인하세요. 한 빌드에서는 네이티브 스크롤이 실제로 더 나빴습니다 (13% 드롭된 프레임 vs 9%) — Lenis는 괜찮았고 실제 비용은 다른 곳에 있었습니다:
- 고정된 전체 뷰포트
mix-blend-mode오버레이 (필름 그레인): 블렌드 모드만 제거하여 34% → 3% 드롭된 프레임 - sticky 요소의
backdrop-filter: 스크롤의 모든 프레임마다 화면에 표시됨 - 일반적으로 큰 요소의
backdrop-filter— 프레임마다 다시 샘플링함
프레임 타이밍 측정 도구
// 페이지 내부
window.__f = []; let l = performance.now();
const t = n => { window.__f.push(n - l); l = n; requestAnimationFrame(t); };
requestAnimationFrame(t);
의심되는 구역에서 실제 휠 이벤트로 구동한 후, 평균, p95, 33ms를 초과하는 프레임 비율을
보고하세요. 한 번에 하나의 효과를 add_style_tag로 비활성화하여 이분법으로 찾습니다.
건강한 수치는 ~16.7ms 평균과 0% 긴 프레임입니다. 약 10% 이상의 긴 프레임은 눈에 띄는
끊김입니다.
체크리스트
-
html에서scroll-behavior: smooth제거됨 - Lenis CSS 블록 추가됨
-
autoRaf: true(또는 수동 RAF 루프 — 둘 다는 안 됨) -
anchors오프셋이 고정 헤더 높이와 일치함 -
syncTouch: false로 폰이 네이티브 모멘텀을 유지함 - 오버레이가 스크롤을 잠그는 동안 sticky 헤더가 고정됨
- 하나의 스크롤 잠금 메커니즘만 활성화됨
- 0이 아닌 스크롤 오프셋에서 오버레이 테스트됨
-
prefers-reduced-motion이 Lenis를 건너뛰고 네이티브 동작을 복원함 - 열기 → 닫기 과정에서 스크롤 위치 유지됨
- 프레임 타이밍이 가정되지 않고 측정됨