Projects › BibleWeb › Bible Reading › Smooth scroll with momentum physics
Needs Design

Smooth scroll with momentum physics

Area: Bible Reading Milestone: v1

Context

Problem: The default browser scrolling can feel abrupt when navigating through long Bible chapters. BibleGame had a custom physics-based scroll that felt luxurious and natural.

Solution: Evaluate whether CSS scroll-behavior: smooth provides adequate feel, or whether a custom momentum-based scroll system is needed.

Not included: Infinite scroll or chapter auto-loading on scroll. This is about the scroll physics, not the scroll content.

Functional

When the user scrolls through a chapter, the scrolling should feel smooth and natural — not abrupt or jerky. The text should decelerate gradually when the user releases a flick gesture.

Expected behavior:

  • Scrolling feels responsive to touch/trackpad input
  • Momentum carries scroll velocity after release
  • Gradual deceleration (no sudden stops)

TODO: Test whether CSS scroll-behavior: smooth is sufficient or if custom physics are needed.

UX & Design

Target feel: Smooth, slightly heavy — like scrolling through a quality reading app (Kindle, Apple Books).

BibleGame reference values:

  • Friction: 0.95 (per frame)
  • Deceleration: gradual exponential decay
  • Custom physics using MonoGame's update loop

TODO: Is native browser smooth scroll good enough? Test on mobile Safari, Chrome, Firefox.

Technical

Option A — CSS only:

html { scroll-behavior: smooth; }

Simplest approach. May be sufficient for most users.

Option B — Custom physics:

  • Capture scroll velocity via touch/wheel events
  • Apply momentum with friction coefficient in requestAnimationFrame loop
  • Port physics from BibleGame's custom scroll system

Reference: BibleGame used custom scroll physics in the MonoGame update loop (friction=0.95, deceleration).

Files:

  • apps/web/src/routes/(app)/read/[[book]]/[[chapter]]/+page.svelte (modify if custom physics)

Status

Current: NEEDS_DESIGN Milestone: v1 Priority: Low — native browser scroll is already decent

History:

  • BibleGame had custom physics (friction=0.95, deceleration) for a premium feel
  • Web browsers have improved native scrolling significantly since BibleGame was built

Dependencies:

  • Requires: chapter reader (DONE)
  • Blocks: nothing

Design questions:

  1. Is CSS scroll-behavior: smooth good enough?
  2. If not, what friction/deceleration values feel right on web?
  3. Should this be mobile-only or also desktop?
← Back to Bible Reading features