# Smooth scroll (Lenis) (`smooth-scroll`)

Lenis smooth wheel scrolling for desktop only, with defaults that keep phones native: no touch hijack, anchors with header offset, paused under modals, instant jumps for keyboard focus.

| | |
|---|---|
| Tag | Flow |
| Size | 1.6 KB gzipped own code (JS 1.2 KB + CSS 0.3 KB; 3.0 KB raw) |
| Dependency | Lenis 1.3.26 (MIT, 5.5 KB gz, vendored) |
| Best for | Editorial pages for salons, med spa, restaurants, studios, on desktop |
| Demo | `index.html` in this folder (live: https://wbl-code-lib.pages.dev/modules/smooth-scroll/) |

## What it does
Starts Lenis only when the visitor has a mouse or trackpad (hover + fine pointer) and hasn't asked for reduced motion; iPhones, Android and iPads keep native momentum scrolling (Lenis' syncTouch stays off, the known source of iOS jank and rubber-band bugs). Anchor links glide with a sticky-header offset; carousels, dialogs, iframes and [data-lenis-prevent] scroll natively; it stops while a <dialog> is open; Tab focus off-screen jumps instantly instead of gliding.

## When to use
- Only on desktop-heavy, photo-led pages where it makes scrolling feel calmer. It's opt-in.
- Pairs well with Scroll scenes (both are scroll-linked).

## Don't
- Turn on touch (data-touch="on"): phones already have momentum, and synced touch breaks iOS overscroll.
- Use with CSS scroll-snap on the page itself or pinned sections.
- Forget the batch 3 tag: smooth scroll is on the 'breaks rule: scroll-jacking' shelf. This wrapper's desktop-only, never-touch defaults are the safest version, but it still changes how scrolling feels: ask Christopher before putting it on a preview.

## Reduced motion, no JS, accessibility
- Reduced motion: never starts (and stops if the setting changes mid-visit).
- No JS / CDN failure: native scrolling (nothing depends on it).
- Keyboard: Space/PageDown/arrows are native; focus jumps are immediate.

## Notes
- Lenis 1.3.26 (Aug 2026), vendored in vendor/ with its MIT licence: 5.4 KB gzipped.
- lerp 0.12 is calmer than the Lenis default 0.1 feels on a 120 Hz trackpad; 0.08-0.15 is the useful range.

## Relation to the effects libraries
Batch 3 has a GSAP ScrollSmoother-style smooth-scroll on the shelf (breaks rule). This is the lightweight Lenis alternative with phone-safe defaults.

## Use it
Copy this folder to the site as `/wbl/smooth-scroll/` (keep `vendor/` if there is one), then:

```html
<!-- Smooth scroll (Lenis) (WBL Code Library) -->
<!-- in <head>: -->
<script>document.documentElement.classList.add('wbl-js')</script>
<link rel="stylesheet" href="/wbl/smooth-scroll/vendor/lenis.css">
<link rel="stylesheet" href="/wbl/smooth-scroll/module.css">
<script src="/wbl/smooth-scroll/vendor/lenis.min.js" defer></script>
<script src="/wbl/smooth-scroll/module.js" defer></script>

<!-- markup: -->
<!-- put the attribute on <html>; nothing else to mark up -->
<html lang="en" data-wbl="smooth-scroll" data-lerp="0.12" data-offset="72">
```

Colours come from CSS variables with safe defaults: `--wbl-accent`, `--wbl-on-accent`, `--wbl-ink`, `--wbl-paper`,
`--wbl-card`, `--wbl-line`, `--wbl-muted`, `--wbl-band`, `--wbl-radius`, `--wbl-head` (see the library README for the
one-line bridge to the preview builder's `--a / --ink / --bg …`).

## License
Our code: WBL-owned, original. Lenis 1.3.26: MIT (https://github.com/darkroomengineering/lenis), licence text in `vendor/`