Overview

Velvet gives React applications native-feeling sheets, stacked surfaces, lightboxes, card expansion, scroll coordination, and toasts. You choose a ready-made composition or assemble the primitives yourself.

Start in three minutes

npm install velvet-ui
# pnpm add velvet-ui
# yarn add velvet-ui

import "velvet-ui/styles.css";
import { Toaster } from "velvet-ui/toast";

export function App() {
  return (
    <>
      <YourApp />
      <Toaster position="bottom-right" />
    </>
  );
}

Use a composition when its behavior matches your product. Use Sheet primitives when you need a different DOM tree, placement, snap model, or visual treatment.

Pick the right entry point

• velvet-ui/sheet — headless sheet primitives.
• velvet-ui/motion — framework-free spring and WAAPI tools.
• velvet-ui/motion/react — motion hooks with cleanup.
• velvet-ui/utilities — Scroll and integration primitives.
• velvet-ui/bottom-sheet — a production bottom sheet.
• velvet-ui/depth-sheet — iOS-style page recession and nesting.
• velvet-ui/card-expansion — a modal card with shared-origin motion.
• velvet-ui/lightbox — full-screen media with bidirectional dismissal.
• velvet-ui/toast — viewport-fixed feedback.

The mental model

A sheet has state, a trigger, a portal, a gesture view, a backdrop, and content. Sheet.Panel composes those parts for the common case. Every open, drag, snap, and close uses the same travel value and spring model.

If an implementation feels stuck, first ask: who owns open, which element scrolls, which direction can dismiss, and whether the page behind should remain interactive?