Smooth Scroll

File: src/config/config.toml · Skill level: Beginner

Scrolling with a mouse wheel or trackpad glides instead of jumping line by line. It uses a small library called Lenis, which the theme loads as a separate file only on devices where it runs.

Smooth scroll stays out of the way when it isn’t wanted:

Phones, tablets, and other touch screens keep their normal touch scrolling. It runs only with a mouse or trackpad.
Visitors who turn on reduce motion in their device settings keep the browser’s normal scrolling.
It is off when [settings.animation] enable = false (see Animations).
Menus, the search window, and other overlays pause it while they are open, and areas with their own scroll, such as the search results, keep native scrolling.

Settings

[settings.smoothScroll]
  enable                = true
  respectReducedMotion  = true
  duration              = 1.0
  easing                = "expo"
  smoothWheel           = true
  syncTouch             = false
  wheelMultiplier       = 1
  touchMultiplier       = 1
  anchors               = true
  autoRaf               = false
  stopInertiaOnNavigate = true

Setting	What it does
`enable`	`false` gives you the browser’s normal scrolling
`respectReducedMotion`	`true` turns smooth scroll off for visitors who ask for reduced motion. Keep it on
`duration`	How long the glide lasts, in seconds. Higher feels slower and smoother
`easing`	The feel of the glide: `expo`, `linear`, `easeOutQuad`, or `easeOutCubic`
`smoothWheel`	Smooths mouse wheel and trackpad scrolling
`syncTouch`	Applies smoothing to touch input on devices that have both a mouse or trackpad and a touchscreen
`wheelMultiplier`	How far one wheel movement scrolls. `1` is normal
`touchMultiplier`	How far one swipe scrolls when `syncTouch` is on. `1` is normal
`anchors`	Glides to `#section` links on the same page instead of jumping, and stops below the header
`autoRaf`	No effect in Margo. The theme always runs Lenis from its own animation loop, shared with the scroll effects
`stopInertiaOnNavigate`	Stops any remaining glide when a visitor clicks a link

To change the feel, adjust duration first. Restart npm run dev if a change doesn’t show.

For Developers

The Lenis instance is available as window.__themeLenis. It only exists where smooth scroll is running, so check for it first:

// Scroll to an element
window.__themeLenis?.scrollTo("#contact");

To pause scrolling while something of yours is open, use the theme’s scroll lock, which also works when several overlays are open at once:

window.__themeMotion?.lock();
window.__themeMotion?.unlock();

An element with its own scroll area, such as a long list in a panel, should keep native scrolling. Add data-lenis-prevent to it:

<div class="overflow-y-auto" data-lenis-prevent>...</div>

The code is in src/lib/motion/smooth.ts.

Do It With AI

Make scrolling feel [SLOWER / FASTER] on my Margo site. In src/config/config.toml, change only the
duration value under [settings.smoothScroll]. Keep respectReducedMotion = true, and
don't change any other key.