Styled compositions
Styled compositions package the visual grammar for common interactions while preserving the underlying primitive API.
Start with a composition when its behavior matches the task. Drop to Sheet primitives only when the DOM, placement, tracks, or visual layers need a different contract.
Decision table
| Need | Use |
|---|---|
| Mobile detail, picker, checkout, short task | BottomSheet |
| Tool or media control that must remain present | PersistentSheet |
| Hierarchical full-width navigation with backing-page depth | DepthSheet |
| A normal card that expands into a modal | CardExpansion |
| Immersive photo or media | Lightbox |
| Drawer, top sheet, modal, detached, full-screen, parallax | Sheet primitives |
Compositions stay headless where it matters
Every Content forwards refs and DOM props and supports asChild. Supply your own view, backdrop, handle, and bleedingBackground elements where that part exists; Velvet composes primitive behavior onto those nodes.
viewProps, portalProps, and part-specific prop bags reach the underlying primitive. The supplied CSS establishes responsive geometry and safe-area behavior, while color and product layout remain overrideable through variables, classes, or replacement components. See Bring your own components.
Imports
import { BottomSheet } from "@velvetui/react/bottom-sheet";
import { CardExpansion } from "@velvetui/react/card-expansion";
import { DepthSheet } from "@velvetui/react/depth-sheet";
import { Lightbox } from "@velvetui/react/lightbox";
import { PersistentSheet } from "@velvetui/react/persistent-sheet";