A minimal slide-up panel for React 18/19.
Live preview • Full docs

Why Sweep • Installation • Quick start • API reference • Styling • Playground

• Drop-in experience – Wrap your app once with SweepWrapper, call useSweep() anywhere, and you have a polished bottom sheet with portals, layering, and scroll locking handled for you.
• Fluid animations – Native Element.animate timelines drive the open/close/replace transitions, including blur, scale, and async switching when you call open twice with different keyed nodes.
• Touch-native gestures – Drag to dismiss, configurable snap point, optional body-blocking, and safeguards for iOS Safari quirks (usePreventScroll) ship built-in.
• Configurable but tiny – Toggle blur, border radius, outside-click behavior, or entirely disable gestures without pulling in CSS frameworks.
• React 18/19 ready – Zero dependency on legacy lifecycles, works in SPA or app-router setups, SSR-safe wrapper (hook throws if used outside the provider so bugs show up fast).

npm install @aiko-lab/sweep
# or
yarn add @aiko-lab/sweep
# or
pnpm add @aiko-lab/sweep

Peer deps: react and react-dom ≥ 18 (the library is authored against 19). No CSS files to import.

1. Wrap your root

import { SweepWrapper } from "@aiko-lab/sweep";

export function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <SweepWrapper
      backgroundColor="rgb(12, 12, 12)" // panel background
      foregroundColor="black" // app background when sheet is open
    >
      {children}
    </SweepWrapper>
  );
}

2. Summon Sweep anywhere

import { useSweep } from "@aiko-lab/sweep";

export function CheckoutButton() {
  const sweep = useSweep(
    {
      blur: true,
      clickBodyToClose: true,
      snapPoint: 96, // px threshold before drag-to-close fires
    },
    {
      onToggle: (isOpen) => console.log("Sheet open?", isOpen),
      onSwitch: (prev, next) => console.log("Swapped", prev, "→", next),
    }
  );

  return (
    <button
      onClick={() =>
        sweep.open(
          <CheckoutSheet key="checkout">
            {/* Important: provide a stable key for switch animations */}
          </CheckoutSheet>
        )
      }
    >
      Review order
    </button>
  );
}

3. Close or replace

const sheet = useSweep();

sheet.open(<Success key="success" />);
sheet.close();

Each call to open with a new keyed element animates from the old sheet to the new one. Calling open with the same key is ignored to avoid flicker.

Wrap exactly once as high in the tree as possible (typically _app.tsx, layout.tsx, or App). It provides context, handles layering, and paints the overlay behind your UI.

When clickBodyToClose is enabled at the hook level, clicking the foreground (body) triggers close automatically.

Returns { open(element: ReactNode), close(): void }. Must be called inside a descendant of SweepWrapper.

Each open call captures the config at call time, so you can vary behavior per sheet (e.g., disable gestures for a payment flow but allow them for a menu).

• Colors – Prefer plain CSS colors via backgroundColor/foregroundColor for simple setups. If you already use Tailwind, pass backgroundClassName="bg-black/80 backdrop-blur" and foregroundClassName="bg-gray-950 text-white".
• Layout – The sheet itself renders exactly what you pass. Bring your own padding, rounded corners, shadows, etc.
• Responsive behavior – Combine snapPoint with responsive logic: const snap = window.innerHeight * 0.25 to mimic native iOS sheets, or disable touch events on desktop entirely.
• Scroll locking – usePreventScroll kicks in automatically when the sheet is open. Inputs keep focus on iOS/Safari thanks to the borrowed Spectrum workaround; no extra config needed.

• Nested flows – Chain open calls with different keys to build multi-step flows. Sweep animates between states without closing.
• Imperative handles – The hook returns plain functions, so you can stash them in refs or state machines easily.
• Server components – Only the SweepWrapper lives near the root; the hook itself is a client-only helper. In Next.js app router, wrap inside a client layout.
• Accessibility – Focus stays inside your content because the rest of the document is scroll-locked and pointer-blocked when configured. Provide focus traps if your sheet hosts forms/dialogs.
• Performance – Animations rely on the Web Animations API for 60fps transforms. Keep your sheet subtree small (lazy-load heavy content right before calling open).

The /test folder contains a Vite demo used to dogfood Sweep.

cd test
npm install
npm run dev

This runs the example shown in the GIF (multi-step sheet with Lucide icons). Point the playground to your local src by keeping the relative import ../../src.

• “useMyContext must be used within a MyProvider” – You called useSweep outside of SweepWrapper. Wrap higher or export helper components that consume the hook internally.
• Drag dismiss feels too sensitive – Increase snapPoint, or set disableTouchEvents: true for that sheet.
• Need to close on route change – Call const sheet = useSweep(); useEffect(() => sheet.close(), [pathname]);.
• Animations not running in tests – Mock Element.animate in your Jest/Vitest setup since JSDOM doesn’t implement it by default.

• Aiko Lab – UI components and experiments.
• Articles – Interactive write-ups from the same author.

MIT © ai-ko.dev · Twitter @username_aiko