lenis-react

Files (3)

• SKILL.md
• accessibility.md · references/
• recipes.md · references/

SKILL.md (first lines)

# Lenis Smooth Scroll — React Integration Skill

## Overview

Lenis (Latin: "smooth") is a lightweight, performant smooth-scroll library by darkroom.engineering. The `lenis/react` sub-package provides a `<ReactLenis>` context provider and a `useLenis` hook, eliminating prop-drilling and tying the RAF loop into React's lifecycle automatically.

**Package landscape (important — use the right import):**

| Package | Status | Import |
|---|---|---|
| `lenis` | ✅ Current (v1+) | `import { ReactLenis, useLenis } from 'lenis/react'` |
| `@studio-freight/lenis` | ⚠️ Legacy | `import Lenis from '@studio-freight/lenis'` |
| `@studio-freight/react-lenis` | ⚠️ Legacy | `import { ReactLenis } from '@studio-freight/react-lenis'` |

Always use the current `lenis` package unless the project explicitly pins to the legacy packages.

---

## 1. Installation

```bash
npm install lenis
# or
yarn add lenis
# or
pnpm add lenis
```

Also add Lenis's required CSS (critical for correct layout):

```css
/* In your global CSS file */
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-smooth iframe {
  pointer-events: none;
}
```

Or import from the package directly:
```js
import 'lenis/dist/lenis.css'
```

---

## 2. Minimal Setup (full-page scroll)

```tsx
// app/layout.tsx  OR  src/main.tsx
import { ReactLenis } from 'lenis/react'

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ReactLenis root>
          {children}
        </ReactLenis>
      </body>
    </html>
  )
}
```

- `root` prop: Lenis hijacks the `<html>` scroll container (the standard full-page case).
- RAF loop is managed automatically when `autoRaf` is not disabled.

---

## 3. Common Configuration Options

Pass options via the `options` prop on `<ReactLenis>`:

```tsx
<ReactLenis
  root
  options={{
    lerp: 0.1,          // Smoothing factor (0–1). Lower = smoother but slower. Default: 0.1
    duration: 1.2,      // Scroll animation duration in seconds (ignored if lerp set)
    easing: (t) => Math.min(1, 1.001 - Math.pow(2, -10 * t)), // Custom easing
    orientation: 'vertical',   // 'vertical' | 'horizontal'
    gestureOrientation: 'vertical', // 'vertical' | 'horizontal' | 'both'
    smoothWheel: true,  // Smooth wheel events (default: true)
    smoothTouch: false, // Smooth touch scroll — keep false unless intentional (can feel unnatural)
    touchMultiplier: 2, // Touch sensitivity
    infinite: false,    // Infinite scroll
  }}
>
  {children}
</ReactLenis>
```

**Decision guide:**
- For most marketing sites: `lerp: 0.08–0.12` feels natural.
- For heavy creative/portfolio sites: `lerp: 0.05–0.08` for extra drag.
- Never set `smoothTouch: true` without thorough iOS testing — can feel laggy.
- Prefer `lerp` over `duration` unless you need deterministic timing (e.g., carousel snapping).

---

## 4. useLenis Hook

`useLenis` returns the Lenis instance and optionally registers a scroll callback:

From 12-Studio/Tackl, MIT.

More from 12-Studio/Tackl