Issue Nº 01 · Apr 2026 · MIT Filed under: gestures · physics · a11y

@surdeddd/ bottom-sheet

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

9KB gzip core / esm

7 adapters

4 modes

138+32 tests · unit + e2e

0 runtime deps

360×720 · bottom mode ↑↓ Esc Tab

Usage react

// React
import { BottomSheet } from "@surdeddd/bottom-sheet/react";
import "@surdeddd/bottom-sheet/styles";

<BottomSheet
  snapPoints={[
    { id: "closed",    size: 0 },
    { id: "minimized", size: 96 },
    { id: "half",      size: "45%" },
    { id: "full",      size: "85%" },
  ]}
  initial="minimized"
  animation="spring"
  spring={{ stiffness: 260, damping: 28 }}
  focusTrap
  closeOnEscape
  backdropRange={[0.4, 1]}
>
  <YourList />
</BottomSheet>

<!-- Vue 3 -->
<script setup>
import { BottomSheet } from "@surdeddd/bottom-sheet/vue";
import "@surdeddd/bottom-sheet/styles";
</script>

<template>
  <BottomSheet
    :snap-points="[
      { id: 'minimized', size: 96 },
      { id: 'half',      size: '45%' },
      { id: 'full',      size: '85%' },
    ]"
    initial="minimized"
    animation="spring"
    focus-trap
    @snap="onSnap"
  >
    <YourList />
  </BottomSheet>
</template>

<!-- Svelte 5 — runes + SFC -->
<script lang="ts">
import { BottomSheet } from "@surdeddd/bottom-sheet/svelte";
import "@surdeddd/bottom-sheet/styles";
let sheet: any = $state();
</script>

<BottomSheet
  bind:this={sheet}
  snapPoints={[
    { id: "min",  size: 96 },
    { id: "half", size: "45%" },
    { id: "full", size: "85%" },
  ]}
  animation="spring"
  onsnap={(id) => console.log(id)}
>
  {#snippet header()}<h2>Title</h2>{/snippet}
  <YourList />
</BottomSheet>

// Solid — engine wired to refs via `ref={...}`
import { BottomSheetEngine } from "@surdeddd/bottom-sheet";
import { onMount } from "solid-js";
import "@surdeddd/bottom-sheet/styles";

let sheetEl, handleEl, contentEl;
onMount(() => {
  new BottomSheetEngine({
    element: sheetEl, handle: handleEl, scrollContainer: contentEl,
    snapPoints: [
      { id: "min",  size: 96 },
      { id: "half", size: "45%" },
      { id: "full", size: "85%" },
    ],
    animation: "spring",
  });
});

<div class="bs-root">
  <section class="bs-sheet" ref={sheetEl}>
    <div class="bs-handle" ref={handleEl}>Header</div>
    <div class="bs-content" ref={contentEl}>…</div>
  </section>
</div>

// Lit — wraps the <bottom-sheet> custom element
import { LitElement, html } from "lit";
import { customElement } from "lit/decorators.js";
import "@surdeddd/bottom-sheet/element";

@customElement("my-sheet")
class MySheet extends LitElement {
  createRenderRoot() { return this; } // inherit page CSS
  render() {
    return html`
      <bottom-sheet
        snap-points='[{"id":"min","size":96},{"id":"full","size":"85%"}]'
        initial="min"
        animation="spring"
      >
        <h2 slot="header">Title</h2>
        <ul>…</ul>
      </bottom-sheet>
    `;
  }
}

<!-- Web Component -->
<link rel="stylesheet" href="/styles.css">
<script type="module" src="/element.js"></script>

<bottom-sheet
  snap-points='[
    {"id":"min","size":96},
    {"id":"half","size":"45%"},
    {"id":"full","size":"85%"}
  ]'
  initial="min"
  animation="spring"
  focus-trap="true"
>
  <h2 slot="header">Title</h2>
  <ul>...</ul>
</bottom-sheet>

// Vanilla — engine wired to plain DOM
import { BottomSheetEngine } from "@surdeddd/bottom-sheet";
import "@surdeddd/bottom-sheet/styles";

const engine = new BottomSheetEngine({
  element:         document.querySelector(".bs-sheet"),
  handle:          document.querySelector(".bs-handle"),
  scrollContainer: document.querySelector(".bs-content"),
  backdrop:        document.querySelector(".bs-backdrop"),
  snapPoints: [
    { id: "min",  size: 96 },
    { id: "half", size: "45%" },
    { id: "full", size: "85%" },
  ],
  animation: "spring",
});
engine.on("snap", ({ id }) => console.log(id));
engine.snapTo("full");

Snap point

Mode

Spring physics (remounts)

stiffness 260 damping 28

Behavior

focus trap close on Esc haptic on snap rubber-band

Scrim

above sheet only tap to close floating action

Advanced playground

Snap-point editor

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

Stress test

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

idle

Theme preset

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

default

What's inside — twelve+

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. Same engine — drawer-side sheets without code duplication. Pointer axis & sign computed.

switch (mode) { ... }

F.05

Pointer-type tuned

Touch flicks: 0.65px/ms threshold, 120ms velocity window. Mouse inertia: 0.4px/ms, 160ms window. Gesture parses what the pointer is.

PointerEvent.pointerType

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 orchestrated, backdrops de-duped, only the topmost owns Escape.

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

Tested

138 unit tests (vitest + happy-dom) covering snap math, spring, gestures, focus trap, scroll lock, manager, vh→dvh, viewport resize. 25 e2e via Playwright on mobile-Chrome. All green.

npm test · npx playwright test

$ npm i @surdeddd/bottom-sheet