Composition API

Compositions are small wrappers around Sheet primitives. They set good interaction defaults, emit stable data hooks, and expose the underlying part props instead of hiding them.

Shared Content escape hatches

BottomSheet

Parts: Root, Trigger, Content, Close, Step, Title, Description, Handle.

Defaults: bottom placement, automatic scroll handoff, edge-swipe prevention, backdrop, handle, and coordinated scrolling.

import { BottomSheet } from "velvet-ui/bottom-sheet";
import "velvet-ui/sheet.css";
import "velvet-ui/bottom-sheet.css";

<BottomSheet.Root>
  <BottomSheet.Trigger>Open cart</BottomSheet.Trigger>
  <BottomSheet.Content
    viewProps={{ snapPoints: ["42lvh", "82lvh"] }}
    scrollViewProps={{ safeArea: "visual-viewport" }}
  >
    <BottomSheet.Title>Your cart</BottomSheet.Title>
    <Cart />
  </BottomSheet.Content>
</BottomSheet.Root>

PersistentSheet

Parts match BottomSheet. Defaults: 88px collapsed detent, a full detent bounded at 720px, dismissible={false}, modal={false}, and no backdrop.

The outer view is click-through while the sheet content remains interactive. Override defaults through viewProps only when the new policy is intentional.

CardExpansion

Parts: Root, Trigger, Content, Close, Title, Description.

Defaults: center placement, top and bottom dismissal, no swipe overshoot, trigger morph, backdrop, and coordinated scrolling.

from accepts "trigger", an Element, a ref, or a falsy value. Set from={false} to keep modal scale travel without source geometry.

Lightbox

Parts: Root, Trigger, Content, Close, Title, Description.

Defaults: full-screen center surface, top and bottom dismissal, no swipe overshoot, black theme backdrop, and scale/fade travel.

DepthSheet

Parts: Root, Page, Content, Trigger, Close, Step, Title, Description, Handle.

Root accepts Sheet state props plus tokens, sheetProps, id, className, style, and DOM props. Page accepts stackingAnimation. Content exposes the shared escape hatches above.

Nested roots reuse the nearest portal host and stack coordinator. There is no supported-depth limit.

Depth tokens