Issue Nº 24 · v0.24.1 · MIT Filed under: gestures · physics · a11y

@surdeddd/ bottom-sheet

A universal sheet engine. One framework-agnostic core, seven adapters, native-feel gestures.

npm i @surdeddd/bottom-sheet
GitHub API docs
26KB gzip core / esm
7 adapters
4 modes
1000+370 unit + e2e tests
0 runtime deps
§ 01 — the anatomy

Five layers, one gesture

Every layer is a real node the engine owns — nothing here is a picture of a sheet.

↓ scroll to build it

  1. .bs-backdrop 01 Backdrop opacity tracks progress
  2. .bs-screen 02 Scrim above-sheet · blur · presets
  3. .bs-sheet 03 Surface translate3d only · 0 reflow
  4. .bs-handle 04 Handle role=slider · drag zones
  5. .bs-content 05 Content scrollable · drag-from-content
+ Preact · Qwik same engine, no live tab here
§ 02 — the device
360×720 · mode: bottom ↑↓ Esc Tab
§ 03 — playground

Snap point

Mode

Spring physics (remounts)

Behavior

The browser paints the sheet. This is the default.

Drag surface

Only the handle starts a drag — the default.

Scrim

§ 04 — advanced

Snap-point editor

Add, remove, edit, reorder snaps. Sheet remounts live.

    Stress test

    Cycle min↔full at decreasing intervals. Watch the FPS.

    idle

    Floating UI

    Anchored elements ride the sheet edge on the compositor; scrim stages swap content per state.

    Theme preset

    Opt-in via class on .bs-root. Loads the theme CSS lazily.

    default

    § 05 — what's inside

    What's inside — sixteen

    F.01

    Spring physics

    Critical-damped harmonic oscillator. Drag velocity carries into the settle — no jerk on flick. Sub-stepped at 240Hz, one DOM write per RAF.

    stiffness · damping · mass
    F.02

    GPU-only motion

    Sized once via height; resized via transform: translate3d. Zero layout per frame. will-change gated to drag/animate.

    60fps drag · 0 reflow
    F.03

    Any CSS length

    Snap points accept px, percentages, fit, full, plus arbitrary CSS: 50dvh, clamp(), env().

    probe-element resolver
    F.04

    Four directions

    bottom · top · left · right, plus logical start / end that follow dir. One engine, so a side drawer is the same sheet on another edge.

    setMode() · rtl-aware
    F.05

    Back button aware

    closeOnBack gives the sheet a history entry, so Back closes it instead of leaving the page. routedTo puts it on its own URL, and await close() waits for the history to settle.

    closeOnBack · routedTo
    F.06

    Native a11y

    role=slider on handle. ↑↓ steps snaps, Home/End jumps, Esc closes. Focus trap with restore. ARIA-live announcer. WCAG 2.1 AA.

    keyboard · screen-reader · inert
    F.07

    Mobile primitives

    env(safe-area-inset-*), hardware-back interception, haptic tick on snap, body scroll lock that's iOS-safe (position:fixed).

    iPhone · Android Chrome
    F.08

    Headless or framed

    Use useBottomSheet() for full JSX control, or grab the ready-made <BottomSheet>. Three layers, your call.

    React · Vue · Svelte · Solid · Lit · WC · core
    F.09

    Multi-sheet stack

    Open a sheet from another sheet. Z-index, the focus trap, inert and Escape follow the stack: only the top sheet owns them.

    sheetStack singleton
    F.10

    SSR-safe

    Zero window at import. useSyncExternalStore with cached snapshot. Optional noSSR prop kills hydration mismatches in Next.js.

    React 18+ · Vue 3+
    F.11

    Sheet manager

    createSheetManager() — typed registry mapping route keys to configs. onOpen/onClose hooks like the original Vue 2 manager, framework-agnostic.

    manager.transition(prev, next)
    F.12

    WebGL renderer

    An opt-in second renderer paints the surface on the GPU: it bends with drag velocity and hands the text back to the DOM when it settles. Layout, scrolling and the accessibility tree never leave the DOM. Switch it on in the workbench above.

    /webgl · 6.4 KB · DOM fallback
    F.13

    Drag zones

    dragFrom: handle, whole sheet, or opt-in [data-bs-drag] islands. [data-bs-no-drag] excludes a subtree, so carousels keep their own gesture.

    setDragFrom · runtime switch
    F.14

    Anchored UI

    Elements ride the sheet edge on the compositor via --bs-size. Scrim stages swap content per state; docked bars let the sheet slide under them.

    anchors · scrim stages
    F.15

    Pay for what you use

    /core is the engine alone at ~22 KB. Route, persist, auto-collapse and the rest are opt-in EngineFeatures you register per instance.

    core 21.9 KB · features 4.2 KB
    F.16

    Debuggable

    attachDebugOverlay(engine) prints live snap, size, progress and flags from public events only — and ships zero bytes into every other bundle.

    /debug · 944 B