Bottom Sheet

When to use it

Use it on phones for a task that needs the screen for a moment but should keep the page visible behind it: filters, a share panel, a detail card, a map list with a half and a full height.

Do not use it for a blocking confirmation (use an alert dialog) or for navigation that should be a page. For a panel that never goes away, use Persistent Sheet. To get a dialog on desktop and a sheet on phones, use Responsive Dialog.

Installation

pnpmnpmyarnbun
pnpm dlx shadcn@latest add https://ui.tealmac.com/r/bottom-sheet.json
Copy

Usage

Copyimport {
  BottomSheet,
  BottomSheetContent,
  BottomSheetDescription,
  BottomSheetHeader,
  BottomSheetTitle,
  BottomSheetTrigger,
} from "@/components/ui/bottom-sheet"

Copy<BottomSheet snapPoints={[0.4, 0.7, 1]}>
  <BottomSheetTrigger asChild>
    <Button>Open</Button>
  </BottomSheetTrigger>
  <BottomSheetContent>
    <BottomSheetHeader>
      <BottomSheetTitle>Nearby</BottomSheetTitle>
      <BottomSheetDescription>Drag to resize.</BottomSheetDescription>
    </BottomSheetHeader>
    ...
  </BottomSheetContent>
</BottomSheet>

Props

Keyboard

• Tab / Shift+Tab: move through the content; focus stays inside the sheet.
• Up / Down on the handle: next or previous snap point. Home / End: lowest or highest.
• Escape: close (unless dismissible is false).

Accessibility

• Built on a Radix dialog: modal, focus is trapped and returned to the trigger, the title and description name it.
• The drag handle is a focusable separator (the WAI-ARIA window splitter pattern) with aria-valuenow and a spoken height, so snap points are reachable without a pointer.
• Only the tallest snap point scrolls the content; lower ones are dragged, so a scroll never fights a drag.
• Drag, snap and slide animations are removed with prefers-reduced-motion.

Testing

The component ships with a Testing Library test (bottom-sheet.test.tsx). jsdom has no layout or touch, so the test checks the dialog semantics, the handle's keyboard control of the snap index and Escape, and that a non-dismissible sheet ignores Escape.